comparison: libpurple/sslconn.h
libpurple/sslconn.h
- changeset 40348
- 6687499c0b4f
- parent 40347
- 1d7bfb35d82f
- child 40349
- 649f7720b294
equal
deleted
inserted
replaced
| 40347:1d7bfb35d82f | 40348:6687499c0b4f |
|---|---|
| 1 /* purple | |
| 2 * | |
| 3 * Purple is the legal property of its developers, whose names are too numerous | |
| 4 * to list here. Please refer to the COPYRIGHT file distributed with this | |
| 5 * source distribution. | |
| 6 * | |
| 7 * This program is free software; you can redistribute it and/or modify | |
| 8 * it under the terms of the GNU General Public License as published by | |
| 9 * the Free Software Foundation; either version 2 of the License, or | |
| 10 * (at your option) any later version. | |
| 11 * | |
| 12 * This program is distributed in the hope that it will be useful, | |
| 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 15 * GNU General Public License for more details. | |
| 16 * | |
| 17 * You should have received a copy of the GNU General Public License | |
| 18 * along with this program; if not, write to the Free Software | |
| 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA | |
| 20 */ | |
| 21 | |
| 22 #ifndef PURPLE_SSLCONN_H | |
| 23 #define PURPLE_SSLCONN_H | |
| 24 /** | |
| 25 * SECTION:sslconn | |
| 26 * @section_id: libpurple-sslconn | |
| 27 * @short_description: <filename>sslconn.h</filename> | |
| 28 * @title: SSL API | |
| 29 */ | |
| 30 | |
| 31 #include <gio/gio.h> | |
| 32 #include "proxy.h" | |
| 33 | |
| 34 #define PURPLE_SSL_DEFAULT_PORT 443 | |
| 35 | |
| 36 typedef struct _PurpleSslConnection PurpleSslConnection; | |
| 37 | |
| 38 typedef void (*PurpleSslInputFunction)(gpointer data, PurpleSslConnection *connection, | |
| 39 PurpleInputCondition cond); | |
| 40 typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *connection, PurpleSslErrorType err, | |
| 41 gpointer data); | |
| 42 | |
| 43 /** | |
| 44 * PurpleSslConnection: | |
| 45 * @host: Hostname to which the SSL connection will be made | |
| 46 * @port: Port to connect to | |
| 47 * @connect_cb_data: Data to pass to @connect_cb | |
| 48 * @connect_cb: Callback triggered once the SSL handshake is complete | |
| 49 * @error_cb: Callback triggered if there is an error during connection | |
| 50 * @recv_cb_data: Data passed to @recv_cb | |
| 51 * @recv_cb: User-defined callback executed when the SSL connection | |
| 52 * receives data | |
| 53 * @fd: File descriptor used to refer to the socket | |
| 54 * @inpa: Glib event source ID; used to refer to the received data | |
| 55 * callback in the glib eventloop | |
| 56 * @connect_data: Data related to the underlying TCP connection | |
| 57 * @conn: The underlying #GTlsConnection | |
| 58 * @cancellable: A cancellable to call when cancelled | |
| 59 * @private_data: Internal connection data managed by the SSL backend | |
| 60 * (GnuTLS/LibNSS/whatever) | |
| 61 */ | |
| 62 struct _PurpleSslConnection | |
| 63 { | |
| 64 char *host; | |
| 65 int port; | |
| 66 void *connect_cb_data; | |
| 67 PurpleSslInputFunction connect_cb; | |
| 68 PurpleSslErrorFunction error_cb; | |
| 69 void *recv_cb_data; | |
| 70 PurpleSslInputFunction recv_cb; | |
| 71 | |
| 72 int fd; | |
| 73 guint inpa; | |
| 74 PurpleProxyConnectData *connect_data; | |
| 75 | |
| 76 GTlsConnection *conn; | |
| 77 GCancellable *cancellable; | |
| 78 | |
| 79 void *private_data; | |
| 80 }; | |
| 81 | |
| 82 G_BEGIN_DECLS | |
| 83 | |
| 84 /**************************************************************************/ | |
| 85 /* SSL API */ | |
| 86 /**************************************************************************/ | |
| 87 | |
| 88 /** | |
| 89 * purple_ssl_connect: (skip) | |
| 90 * @account: The account making the connection. | |
| 91 * @host: The destination host. | |
| 92 * @port: The destination port. | |
| 93 * @func: The SSL input handler function. | |
| 94 * @error_func: The SSL error handler function. This function | |
| 95 * should <emphasis>NOT</emphasis> call purple_ssl_close(). In | |
| 96 * the event of an error the #PurpleSslConnection will be | |
| 97 * destroyed for you. | |
| 98 * @data: User-defined data. | |
| 99 * | |
| 100 * Makes a SSL connection to the specified host and port. The caller | |
| 101 * should keep track of the returned value and use it to cancel the | |
| 102 * connection, if needed. | |
| 103 * | |
| 104 * Returns: The SSL connection handle. | |
| 105 */ | |
| 106 PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host, | |
| 107 int port, PurpleSslInputFunction func, | |
| 108 PurpleSslErrorFunction error_func, | |
| 109 void *data); | |
| 110 | |
| 111 /** | |
| 112 * purple_ssl_connect_with_ssl_cn: (skip) | |
| 113 * @account: The account making the connection. | |
| 114 * @host: The destination host. | |
| 115 * @port: The destination port. | |
| 116 * @func: The SSL input handler function. | |
| 117 * @error_func: The SSL error handler function. This function | |
| 118 * should <emphasis>NOT</emphasis> call purple_ssl_close(). In | |
| 119 * the event of an error the #PurpleSslConnection will be | |
| 120 * destroyed for you. | |
| 121 * @ssl_host: The hostname of the other peer (to verify the CN) | |
| 122 * @data: User-defined data. | |
| 123 * | |
| 124 * Makes a SSL connection to the specified host and port, using the separate | |
| 125 * name to verify with the certificate. The caller should keep track of the | |
| 126 * returned value and use it to cancel the connection, if needed. | |
| 127 * | |
| 128 * Returns: The SSL connection handle. | |
| 129 */ | |
| 130 PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host, | |
| 131 int port, PurpleSslInputFunction func, | |
| 132 PurpleSslErrorFunction error_func, | |
| 133 const char *ssl_host, | |
| 134 void *data); | |
| 135 | |
| 136 /** | |
| 137 * purple_ssl_connect_with_host_fd: (skip) | |
| 138 * @account: The account making the connection. | |
| 139 * @fd: The file descriptor. | |
| 140 * @func: The SSL input handler function. | |
| 141 * @error_func: The SSL error handler function. | |
| 142 * @host: The hostname of the other peer (to verify the CN) | |
| 143 * @data: User-defined data. | |
| 144 * | |
| 145 * Makes a SSL connection using an already open file descriptor. | |
| 146 * | |
| 147 * Returns: The SSL connection handle. | |
| 148 */ | |
| 149 PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd, | |
| 150 PurpleSslInputFunction func, | |
| 151 PurpleSslErrorFunction error_func, | |
| 152 const char *host, | |
| 153 void *data); | |
| 154 | |
| 155 /** | |
| 156 * purple_ssl_input_add: (skip) | |
| 157 * @gsc: The SSL connection handle. | |
| 158 * @func: The callback function. | |
| 159 * @data: User-defined data. | |
| 160 * | |
| 161 * Adds an input watcher for the specified SSL connection. | |
| 162 * Once the SSL handshake is complete, use this to watch for actual data across it. | |
| 163 */ | |
| 164 void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func, | |
| 165 void *data); | |
| 166 | |
| 167 /** | |
| 168 * purple_ssl_input_remove: (skip) | |
| 169 * @gsc: The SSL connection handle. | |
| 170 * | |
| 171 * Removes an input watcher, added with purple_ssl_input_add(). | |
| 172 * | |
| 173 * If there is no input watcher set, does nothing. | |
| 174 */ | |
| 175 void | |
| 176 purple_ssl_input_remove(PurpleSslConnection *gsc); | |
| 177 | |
| 178 /** | |
| 179 * purple_ssl_close: (skip) | |
| 180 * @gsc: The SSL connection to close. | |
| 181 * | |
| 182 * Closes a SSL connection. | |
| 183 */ | |
| 184 void purple_ssl_close(PurpleSslConnection *gsc); | |
| 185 | |
| 186 /** | |
| 187 * purple_ssl_read: (skip) | |
| 188 * @gsc: The SSL connection handle. | |
| 189 * @buffer: The destination buffer. | |
| 190 * @len: The maximum number of bytes to read. | |
| 191 * | |
| 192 * Reads data from an SSL connection. | |
| 193 * | |
| 194 * Returns: The number of bytes read. | |
| 195 */ | |
| 196 size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len); | |
| 197 | |
| 198 /** | |
| 199 * purple_ssl_write: (skip) | |
| 200 * @gsc: The SSL connection handle. | |
| 201 * @buffer: The buffer to write. | |
| 202 * @len: The length of the data to write. | |
| 203 * | |
| 204 * Writes data to an SSL connection. | |
| 205 * | |
| 206 * Returns: The number of bytes written. | |
| 207 */ | |
| 208 size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len); | |
| 209 | |
| 210 /** | |
| 211 * purple_ssl_get_peer_certificates: (skip) | |
| 212 * @gsc: The SSL connection handle | |
| 213 * | |
| 214 * Obtains the peer's presented certificates | |
| 215 * | |
| 216 * Returns: (element-type GTlsCertificate): The peer certificate chain, in the | |
| 217 * order of certificate, issuer, issuer's issuer, etc. %NULL if no | |
| 218 * certificates have been provided. | |
| 219 */ | |
| 220 GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc); | |
| 221 | |
| 222 /**************************************************************************/ | |
| 223 /* Subsystem API */ | |
| 224 /**************************************************************************/ | |
| 225 | |
| 226 /** | |
| 227 * purple_ssl_init: | |
| 228 * | |
| 229 * Initializes the SSL subsystem. | |
| 230 */ | |
| 231 void purple_ssl_init(void); | |
| 232 | |
| 233 /** | |
| 234 * purple_ssl_uninit: | |
| 235 * | |
| 236 * Uninitializes the SSL subsystem. | |
| 237 */ | |
| 238 void purple_ssl_uninit(void); | |
| 239 | |
| 240 G_END_DECLS | |
| 241 | |
| 242 #endif /* PURPLE_SSLCONN_H */ |
