Debian Codegraph @

deps/libneon/doc/man/ne_session_create.3

raw
1 '\" t
2 .\" Title: ne_session_create
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_SESSION_CREATE" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy \- set up HTTP sessions
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_session\&.h>
37 .fi
38 .ft
39 .HP \w'ne_session\ *ne_session_create('u
40 .BI "ne_session *ne_session_create(const\ char\ *" "scheme" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
41 .HP \w'void\ ne_session_proxy('u
42 .BI "void ne_session_proxy(ne_session\ *" "session" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
43 .HP \w'void\ ne_close_connection('u
44 .BI "void ne_close_connection(ne_session\ *" "session" ");"
45 .HP \w'void\ ne_session_destroy('u
46 .BI "void ne_session_destroy(ne_session\ *" "session" ");"
47 .SH "DESCRIPTION"
48 .PP
49 An
50 \fBne_session\fR
51 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\&.
52 .PP
53 A new HTTP session is created using
54 \fBne_session_create\fR, giving the
55 \fIhostname\fR
56 and
57 \fIport\fR
58 of the server to use, along with the
59 \fIscheme\fR
60 used to contact the server (usually
61 "http")\&. Before the first use of
62 \fBne_session_create\fR
63 in a process,
64 ne_sock_init
65 must have been called to perform any global initialization needed by any libraries used by neon\&.
66 .PP
67 To enable SSL/TLS for the session, pass the string
68 "https"
69 as the
70 \fIscheme\fR
71 parameter, and either register a certificate verification function (see
72 ne_ssl_set_verify) or trust the appropriate certificate (see
73 ne_ssl_trust_cert,
74 ne_ssl_trust_default_ca)\&.
75 .PP
76 If an HTTP proxy server should be used for the session,
77 \fBne_session_proxy\fR
78 must be called giving the hostname and port on which to contact the proxy\&.
79 .PP
80 Further per\-session options may be changed using the
81 ne_set_request_flag
82 interface\&.
83 .PP
84 If it is known that the session will not be used for a significant period of time,
85 \fBne_close_connection\fR
86 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\&.
87 .PP
88 Once a session has been completed,
89 \fBne_session_destroy\fR
90 must be called to destroy the resources associated with the session\&. Any subsequent use of the session pointer produces undefined behaviour\&.
91 .SH "NOTES"
92 .PP
93 The hostname passed to
94 \fBne_session_create\fR
95 is resolved when the first request using the session is dispatched; a DNS resolution failure can only be detected at that time (using the
96 NE_LOOKUP
97 error code); see
98 ne_request_dispatch
99 for details\&.
100 .SH "RETURN VALUES"
101 .PP
102 \fBne_session_create\fR
103 will return a pointer to a new session object (and never
104 NULL)\&.
105 .SH "EXAMPLES"
106 .PP
107 Create and destroy a session:
108 .sp
109 .if n \{\
110 .RS 4
111 .\}
112 .nf
113 ne_session *sess;
114 sess = ne_session_create("http", "host\&.example\&.com", 80);
115 /* \&.\&.\&. use sess \&.\&.\&. */
116 ne_session_destroy(sess);
117 .fi
118 .if n \{\
119 .RE
120 .\}
121 .SH "SEE ALSO"
122 .PP
123 ne_ssl_set_verify,
124 ne_ssl_trust_cert,
125 ne_sock_init,
126 ne_set_session_flag
127 .SH "AUTHOR"
128 .PP
129 \fBJoe Orton\fR <\&[email protected]\&>
130 .RS 4
131 Author.
132 .RE
133 .SH "COPYRIGHT"
134 .br