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