ne_session_create - set up HTTP sessions
#include <ne_session.h> ne_session *ne_session_create(const char *scheme, const char *hostname, unsigned int port); void ne_close_connection(ne_session *session); void ne_session_destroy(ne_session *session);
NE_SESSION_CREATE(3) neon API reference NE_SESSION_CREATE(3)
NAME
ne_session_create, ne_close_connection, 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_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 the ne_session_create function; the
hostname and port parameters specify the origin server to use, along
with the scheme (usually "http"). Before the first use of
ne_session_create in a process, ne_sock_init must have been called to
perform 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) or trust the appropriate certificate
(see ne_ssl_trust_cert, ne_ssl_trust_default_ca).
To use a proxy server for the session, it must be configured (see
ne_session_proxy) before any requests are created from session object.
Further per-session options may be changed using the
ne_set_session_flag interface.
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
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.
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. The session object
must not be destroyed until after all associated request objects have
been destroyed.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/neon |
+---------------+------------------+
|Stability | Volatile |
+---------------+------------------+
NOTES
The hostname passed to ne_session_create 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.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from
http://www.webdav.org/neon/neon-0.30.1.tar.gz.
Further information about this software can be found on the open source
community website at http://www.webdav.org/neon/.
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, ne_ssl_trust_cert, ne_sock_init, ne_set_session_flag
AUTHOR
Joe Orton <neon@lists.manyfish.co.uk>
Author.
COPYRIGHT
neon 0.30.1 23 September 2014 NE_SESSION_CREATE(3)