1NE_SESSION_CREATE(3)          neon API reference          NE_SESSION_CREATE(3)
2
3
4

NAME

6       ne_session_create, ne_close_connection, ne_session_proxy,
7       ne_session_destroy - set up HTTP sessions
8

SYNOPSIS

10       #include <ne_session.h>
11
12       ne_session *ne_session_create(const char *scheme, const char *hostname,
13                                     unsigned int port);
14
15       void ne_session_proxy(ne_session *session, const char *hostname,
16                             unsigned int port);
17
18       void ne_close_connection(ne_session *session);
19
20       void ne_session_destroy(ne_session *session);
21

DESCRIPTION

23       An ne_session object represents an HTTP session - a logical grouping of
24       a sequence of HTTP requests made to a certain server. Any requests made
25       using the session can use a persistent connection, share cached
26       authentication credentials and any other common attributes.
27
28       A new HTTP session is created using ne_session_create, giving the
29       hostname and port of the server to use, along with the scheme used to
30       contact the server (usually "http"). Before the first use of
31       ne_session_create in a process, ne_sock_init must have been called to
32       perform any global initialization needed by any libraries used by neon.
33
34       To enable SSL/TLS for the session, pass the string "https" as the
35       scheme parameter, and either register a certificate verification
36       function (see ne_ssl_set_verify) or trust the appropriate certificate
37       (see ne_ssl_trust_cert, ne_ssl_trust_default_ca).
38
39       If an HTTP proxy server should be used for the session,
40       ne_session_proxy must be called giving the hostname and port on which
41       to contact the proxy.
42
43       Further per-session options may be changed using the
44       ne_set_request_flag interface.
45
46       If it is known that the session will not be used for a significant
47       period of time, ne_close_connection can be called to close the
48       connection, if one remains open. Use of this function is entirely
49       optional, but it must not be called if there is a request active using
50       the session.
51
52       Once a session has been completed, ne_session_destroy must be called to
53       destroy the resources associated with the session. Any subsequent use
54       of the session pointer produces undefined behaviour.
55

NOTES

57       The hostname passed to ne_session_create is resolved when the first
58       request using the session is dispatched; a DNS resolution failure can
59       only be detected at that time (using the NE_LOOKUP error code); see
60       ne_request_dispatch for details.
61

RETURN VALUES

63       ne_session_create will return a pointer to a new session object (and
64       never NULL).
65

EXAMPLES

67       Create and destroy a session:
68
69           ne_session *sess;
70           sess = ne_session_create("http", "host.example.com", 80);
71           /* ... use sess ... */
72           ne_session_destroy(sess);
73

SEE ALSO

75       ne_ssl_set_verify, ne_ssl_trust_cert, ne_sock_init, ne_set_session_flag
76

AUTHOR

78       Joe Orton <neon@lists.manyfish.co.uk>
79           Author.
80

82neon 0.29.3                     11 January 2010           NE_SESSION_CREATE(3)
Impressum