NE_SESSION_CREATE(3) neon API reference NE_SESSION_CREATE(3)NAME
ne_session_create, ne_close_connection, ne_session_proxy, ne_ses‐
sion_destroy - set up HTTP sessions
SYNOPSIS
#include <ne_session.h>
ne_session *ne_session_create (const char *scheme,
const char *hostname,
unsigned int port);
void ne_session_proxy (ne_session *session, const char *hostname,
unsigned int port);
void ne_close_connection (ne_session *session);
void ne_session_destroy (ne_session *session);
DESCRIPTION
An ne_session 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 authen‐
tication credentials and any other common attributes.
A new HTTP session is created using ne_session_create, giving the host‐
name and port of the server to use, along with the scheme used to con‐
tact the server (usually "http"). Before the first use of ne_ses‐
sion_create in a process, ne_sock_init(3) must have been called to per‐
form any global initialization needed by any libraries used by neon.
To enable SSL/TLS for the session, pass the string "https" as the
scheme parameter, and either register a certificate verification func‐
tion (see ne_ssl_set_verify(3)) or trust the appropriate certificate
(see ne_ssl_trust_cert(3), ne_ssl_trust_default_ca(3)).
If an HTTP proxy server should be used for the session, ne_ses‐
sion_proxy must be called giving the hostname and port on which to con‐
tact the proxy.
If it is known that the session will not be used for a significant pe‐
riod of time, ne_close_connection can be called to close the connec‐
tion, 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 ses‐
sion.
Once a session has been completed, ne_session_destroy must be called to
destroy the resources associated with the session. Any subsequent use
of the session pointer produces undefined behaviour.
NOTES
The hostname passed to ne_session_create is resolved when the first re‐
quest using the session is dispatched; a DNS resolution failure can on‐
ly be detected at that time (using the NE_LOOKUP error code); see
ne_request_dispatch(3) for details.
RETURN VALUES
ne_session_create will return a pointer to a new session object (and
never NULL).
EXAMPLES
Create and destroy a session:
ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
/* ... use sess ... */
ne_session_destroy(sess);
SEE ALSOne_ssl_set_verify(3), ne_ssl_trust_cert(3), ne_sock_init(3)AUTHOR
Joe Orton <neon@webdav.org>.
neon 0.25.5 20 January 2006 NE_SESSION_CREATE(3)