NE_SESSION_CREATE(3)						neon API reference					      NE_SESSION_CREATE(3)

NAME

       ne_session_create, ne_close_connection, ne_session_proxy, ne_session_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 authentication credentials and any other common attributes.

       A new HTTP session is created using ne_session_create, giving the hostname and port of the server to use, along with  the  scheme  used	to
       contact	the server (usually "http"). Before the first use of ne_session_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 function
       (see ne_ssl_set_verify(3)) or load the appropriate CA certificate (see ne_ssl_load_ca(3), ne_ssl_load_default_ca(3)).

       If  an  HTTP  proxy server should be used for the session, ne_session_proxy must be called giving the hostname and port on which to contact
       the proxy.

       If it is known that the session will not be used for a significant period 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 request using the session is dispached; a DNS resolution failure can
       only 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 ALSO

       ne_ssl_set_verify(3), ne_ssl_load_ca(3), ne_sock_init(3)

AUTHOR

       Joe Orton <neon@webdav.org>.

neon 0.23.5							   8 October 2002					      NE_SESSION_CREATE(3)