1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
/*
HTTP session handling
Copyright (C) 1999-2003, Joe Orton <joe@manyfish.co.uk>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA
*/
#ifndef NE_SESSION_H
#define NE_SESSION_H 1
#include <sys/types.h>
#include "ne_ssl.h"
#include "ne_uri.h" /* for ne_uri */
#include "ne_defs.h"
BEGIN_NEON_DECLS
typedef struct ne_session_s ne_session;
/* Create a session to the given server, using the given scheme. If
* "https" is passed as the scheme, SSL will be used to connect to the
* server. */
ne_session *ne_session_create(const char *scheme,
const char *hostname, unsigned int port);
/* Finish an HTTP session */
void ne_session_destroy(ne_session *sess);
/* Prematurely force the connection to be closed for the given
* session. */
void ne_close_connection(ne_session *sess);
/* Set the proxy server to be used for the session. */
void ne_session_proxy(ne_session *sess,
const char *hostname, unsigned int port);
/* Set protocol options for session:
* expect100: Defaults to OFF
* persist: Defaults to ON
*
* expect100: When set, send the "Expect: 100-continue" request header
* with requests with bodies.
*
* persist: When set, use a persistent connection. (Generally,
* you don't want to turn this off.)
* */
void ne_set_expect100(ne_session *sess, int use_expect100);
void ne_set_persist(ne_session *sess, int persist);
/* Progress callback. */
typedef void (*ne_progress)(void *userdata, off_t progress, off_t total);
/* Set a progress callback for the session. */
void ne_set_progress(ne_session *sess,
ne_progress progress, void *userdata);
/* Store an opaque context for the session, 'priv' is returned by a
* call to ne_session_get_private with the same ID. */
void ne_set_session_private(ne_session *sess, const char *id, void *priv);
void *ne_get_session_private(ne_session *sess, const char *id);
typedef enum {
ne_conn_namelookup, /* lookup up hostname (info = hostname) */
ne_conn_connecting, /* connecting to host (info = hostname) */
ne_conn_connected, /* connected to host (info = hostname) */
ne_conn_secure /* connection now secure (info = crypto level) */
} ne_conn_status;
typedef void (*ne_notify_status)(void *userdata,
ne_conn_status status,
const char *info);
/* Set a status notification callback for the session, to report
* connection status. */
void ne_set_status(ne_session *sess,
ne_notify_status status, void *userdata);
/* Certificate verification failures.
* The certificate is not yet valid: */
#define NE_SSL_NOTYETVALID (0x01)
/* The certificate has expired: */
#define NE_SSL_EXPIRED (0x02)
/* The hostname for which the certificate was issued does not
* match the hostname of the server; this could mean that the
* connection is being intercepted: */
#define NE_SSL_IDMISMATCH (0x04)
/* The certificate authority which signed the server certificate is
* not trusted: there is no indicatation the server is who they claim
* to be: */
#define NE_SSL_UNTRUSTED (0x08)
/* The bitmask of known failure bits: if (failures & ~NE_SSL_FAILMASK)
* is non-zero, an unrecognized failure is given, and the verification
* should be failed. */
#define NE_SSL_FAILMASK (0x0f)
/* A callback which is used when server certificate verification is
* needed. The reasons for verification failure are given in the
* 'failures' parameter, which is a binary OR of one or more of the
* above NE_SSL_* values. failures is guaranteed to be non-zero. The
* callback must return zero to accept the certificate: a non-zero
* return value will fail the SSL negotiation. */
typedef int (*ne_ssl_verify_fn)(void *userdata, int failures,
const ne_ssl_certificate *cert);
/* Install a callback to handle server certificate verification. This
* is required when the CA certificate is not known for the server
* certificate, or the server cert has other verification problems. */
void ne_ssl_set_verify(ne_session *sess, ne_ssl_verify_fn fn, void *userdata);
/* Use the given client certificate for the session. The client cert
* MUST be in the decrypted state, otherwise behaviour is undefined. */
void ne_ssl_set_clicert(ne_session *sess, const ne_ssl_client_cert *clicert);
/* Indicate that the certificate 'cert' is trusted; 'cert' is
* duplicated internally and may be destroyed at will. */
void ne_ssl_trust_cert(ne_session *sess, const ne_ssl_certificate *cert);
/* If the SSL library provided a default set of CA certificates, trust
* this set of CAs. */
void ne_ssl_trust_default_ca(ne_session *sess);
/* Callback used to load a client certificate on demand. If dncount
* is > 0, the 'dnames' array dnames[0] through dnames[dncount-1]
* gives the list of CA names which the server indicated were
* acceptable. The callback should load an appropriate client
* certificate and then pass it to 'ne_ssl_set_clicert'. */
typedef void (*ne_ssl_provide_fn)(void *userdata, ne_session *sess,
const ne_ssl_dname *const *dnames,
int dncount);
/* Register a function to be called when the server requests a client
* certificate. */
void ne_ssl_provide_clicert(ne_session *sess,
ne_ssl_provide_fn fn, void *userdata);
/* Set the timeout (in seconds) used when reading from a socket. The
* timeout value must be greater than zero. */
void ne_set_read_timeout(ne_session *sess, int timeout);
/* Sets the user-agent string. neon/VERSION will be appended, to make
* the full header "User-Agent: product neon/VERSION".
* If this function is not called, the User-Agent header is not sent.
* The product string must follow the RFC2616 format, i.e.
* product = token ["/" product-version]
* product-version = token
* where token is any alpha-numeric-y string [a-zA-Z0-9]* */
void ne_set_useragent(ne_session *sess, const char *product);
/* Returns non-zero if next-hop server does not claim compliance to
* HTTP/1.1 or later. */
int ne_version_pre_http11(ne_session *sess);
/* Returns the 'hostport' URI segment for the end-server, e.g.
* "my.server.com:8080". */
const char *ne_get_server_hostport(ne_session *sess);
/* Returns the URL scheme being used for the current session, omitting
* the trailing ':'; e.g. "http" or "https". */
const char *ne_get_scheme(ne_session *sess);
/* Sets the host, scheme, and port fields (and no others) of the given
* URI structure; host and scheme are malloc-allocated. */
void ne_fill_server_uri(ne_session *sess, ne_uri *uri);
/* Set the error string for the session; takes printf-like format
* string. */
void ne_set_error(ne_session *sess, const char *format, ...)
#ifdef __GNUC__
__attribute__ ((format (printf, 2, 3)))
#endif /* __GNUC__ */
;
/* Retrieve the error string for the session */
const char *ne_get_error(ne_session *sess);
END_NEON_DECLS
#endif /* NE_SESSION_H */
|
