ne_session_create(3)

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,   ne_ses‐
7       sion_destroy - set up HTTP sessions
8

SYNOPSIS

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

DESCRIPTION

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

NOTES

63       The hostname passed to ne_session_create is resolved when the first re‐
64       quest using the session is dispatched; a DNS resolution failure can on‐
65       ly  be  detected  at  that  time  (using the NE_LOOKUP error code); see
66       ne_request_dispatch(3) for details.
67
68

RETURN VALUES

70       ne_session_create will return a pointer to a new  session  object  (and
71       never NULL).
72
73

EXAMPLES

75       Create and destroy a session:
76
77       ne_session *sess;
78       sess = ne_session_create("http", "host.example.com", 80);
79       /* ... use sess ... */
80       ne_session_destroy(sess);
81
82
83

AUTHOR

89       Joe Orton <neon@webdav.org>.
90
91
92
93neon 0.25.5                     20 January 2006           NE_SESSION_CREATE(3)