1.1 --- a/Frameworks/libpurple.framework/Versions/0.5.6/Headers/sslconn.h Sun Jun 21 22:04:11 2009 -0400
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,318 +0,0 @@
1.4 -/**
1.5 - * @file sslconn.h SSL API
1.6 - * @ingroup core
1.7 - */
1.8 -
1.9 -/* purple
1.10 - *
1.11 - * Purple is the legal property of its developers, whose names are too numerous
1.12 - * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 - * source distribution.
1.14 - *
1.15 - * This program is free software; you can redistribute it and/or modify
1.16 - * it under the terms of the GNU General Public License as published by
1.17 - * the Free Software Foundation; either version 2 of the License, or
1.18 - * (at your option) any later version.
1.19 - *
1.20 - * This program is distributed in the hope that it will be useful,
1.21 - * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 - * GNU General Public License for more details.
1.24 - *
1.25 - * You should have received a copy of the GNU General Public License
1.26 - * along with this program; if not, write to the Free Software
1.27 - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 - */
1.29 -#ifndef _PURPLE_SSLCONN_H_
1.30 -#define _PURPLE_SSLCONN_H_
1.31 -
1.32 -/** Possible SSL errors. */
1.33 -typedef enum
1.34 -{
1.35 - PURPLE_SSL_HANDSHAKE_FAILED = 1,
1.36 - PURPLE_SSL_CONNECT_FAILED = 2,
1.37 - PURPLE_SSL_CERTIFICATE_INVALID = 3
1.38 -} PurpleSslErrorType;
1.39 -
1.40 -#include "certificate.h"
1.41 -#include "proxy.h"
1.42 -
1.43 -#define PURPLE_SSL_DEFAULT_PORT 443
1.44 -
1.45 -/** @copydoc _PurpleSslConnection */
1.46 -typedef struct _PurpleSslConnection PurpleSslConnection;
1.47 -
1.48 -typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
1.49 - PurpleInputCondition);
1.50 -typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *, PurpleSslErrorType,
1.51 - gpointer);
1.52 -
1.53 -struct _PurpleSslConnection
1.54 -{
1.55 - /** Hostname to which the SSL connection will be made */
1.56 - char *host;
1.57 - /** Port to connect to */
1.58 - int port;
1.59 - /** Data to pass to PurpleSslConnection::connect_cb() */
1.60 - void *connect_cb_data;
1.61 - /** Callback triggered once the SSL handshake is complete */
1.62 - PurpleSslInputFunction connect_cb;
1.63 - /** Callback triggered if there is an error during connection */
1.64 - PurpleSslErrorFunction error_cb;
1.65 - /** Data passed to PurpleSslConnection::recv_cb() */
1.66 - void *recv_cb_data;
1.67 - /** User-defined callback executed when the SSL connection receives data */
1.68 - PurpleSslInputFunction recv_cb;
1.69 -
1.70 - /** File descriptor used to refer to the socket */
1.71 - int fd;
1.72 - /** Glib event source ID; used to refer to the received data callback
1.73 - * in the glib eventloop */
1.74 - guint inpa;
1.75 - /** Data related to the underlying TCP connection */
1.76 - PurpleProxyConnectData *connect_data;
1.77 -
1.78 - /** Internal connection data managed by the SSL backend (GnuTLS/LibNSS/whatever) */
1.79 - void *private_data;
1.80 -
1.81 - /** Verifier to use in authenticating the peer */
1.82 - PurpleCertificateVerifier *verifier;
1.83 -};
1.84 -
1.85 -/**
1.86 - * SSL implementation operations structure.
1.87 - *
1.88 - * Every SSL implementation must provide all of these and register it via purple_ssl_set_ops()
1.89 - * These should not be called directly! Instead, use the purple_ssl_* functions.
1.90 - */
1.91 -typedef struct
1.92 -{
1.93 - /** Initializes the SSL system provided.
1.94 - * @return @a TRUE if initialization succeeded
1.95 - * @see purple_ssl_init
1.96 - */
1.97 - gboolean (*init)(void);
1.98 - /** Unloads the SSL system. Inverse of PurpleSslOps::init.
1.99 - * @see purple_ssl_uninit
1.100 - */
1.101 - void (*uninit)(void);
1.102 - /** Sets up the SSL connection for a #PurpleSslConnection once
1.103 - * the TCP connection has been established
1.104 - * @see purple_ssl_connect
1.105 - */
1.106 - void (*connectfunc)(PurpleSslConnection *gsc);
1.107 - /** Destroys the internal data of the SSL connection provided.
1.108 - * Freeing gsc itself is left to purple_ssl_close()
1.109 - * @see purple_ssl_close
1.110 - */
1.111 - void (*close)(PurpleSslConnection *gsc);
1.112 - /** Reads data from a connection (like POSIX read())
1.113 - * @param gsc Connection context
1.114 - * @param data Pointer to buffer to drop data into
1.115 - * @param len Maximum number of bytes to read
1.116 - * @return Number of bytes actually written into @a data (which may be
1.117 - * less than @a len), or <0 on error
1.118 - * @see purple_ssl_read
1.119 - */
1.120 - size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len);
1.121 - /** Writes data to a connection (like POSIX send())
1.122 - * @param gsc Connection context
1.123 - * @param data Data buffer to send data from
1.124 - * @param len Number of bytes to send from buffer
1.125 - * @return The number of bytes written to @a data (may be less than
1.126 - * @a len) or <0 on error
1.127 - * @see purple_ssl_write
1.128 - */
1.129 - size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len);
1.130 - /** Obtains the certificate chain provided by the peer
1.131 - *
1.132 - * @param gsc Connection context
1.133 - * @return A newly allocated list containing the certificates
1.134 - * the peer provided.
1.135 - * @see PurpleCertificate
1.136 - * @todo Decide whether the ordering of certificates in this
1.137 - * list can be guaranteed.
1.138 - */
1.139 - GList * (* get_peer_certificates)(PurpleSslConnection * gsc);
1.140 -
1.141 - void (*_purple_reserved2)(void);
1.142 - void (*_purple_reserved3)(void);
1.143 - void (*_purple_reserved4)(void);
1.144 -} PurpleSslOps;
1.145 -
1.146 -#ifdef __cplusplus
1.147 -extern "C" {
1.148 -#endif
1.149 -
1.150 -/**************************************************************************/
1.151 -/** @name SSL API */
1.152 -/**************************************************************************/
1.153 -/*@{*/
1.154 -
1.155 -/**
1.156 - * Returns whether or not SSL is currently supported.
1.157 - *
1.158 - * @return @a TRUE if SSL is supported, or @a FALSE otherwise.
1.159 - */
1.160 -gboolean purple_ssl_is_supported(void);
1.161 -
1.162 -/**
1.163 - * Returns a human-readable string for an SSL error.
1.164 - *
1.165 - * @param error Error code
1.166 - * @return Human-readable error explanation
1.167 - */
1.168 -const gchar * purple_ssl_strerror(PurpleSslErrorType error);
1.169 -
1.170 -/**
1.171 - * Makes a SSL connection to the specified host and port. The caller
1.172 - * should keep track of the returned value and use it to cancel the
1.173 - * connection, if needed.
1.174 - *
1.175 - * @param account The account making the connection.
1.176 - * @param host The destination host.
1.177 - * @param port The destination port.
1.178 - * @param func The SSL input handler function.
1.179 - * @param error_func The SSL error handler function. This function
1.180 - * should <strong>NOT</strong> call purple_ssl_close(). In
1.181 - * the event of an error the #PurpleSslConnection will be
1.182 - * destroyed for you.
1.183 - * @param data User-defined data.
1.184 - *
1.185 - * @return The SSL connection handle.
1.186 - */
1.187 -PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host,
1.188 - int port, PurpleSslInputFunction func,
1.189 - PurpleSslErrorFunction error_func,
1.190 - void *data);
1.191 -
1.192 -#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_SSLCONN_C_)
1.193 -/**
1.194 - * Makes a SSL connection using an already open file descriptor.
1.195 - *
1.196 - * @deprecated Use purple_ssl_connect_with_host_fd() instead.
1.197 - *
1.198 - * @param account The account making the connection.
1.199 - * @param fd The file descriptor.
1.200 - * @param func The SSL input handler function.
1.201 - * @param error_func The SSL error handler function.
1.202 - * @param data User-defined data.
1.203 - *
1.204 - * @return The SSL connection handle.
1.205 - */
1.206 -PurpleSslConnection *purple_ssl_connect_fd(PurpleAccount *account, int fd,
1.207 - PurpleSslInputFunction func,
1.208 - PurpleSslErrorFunction error_func,
1.209 - void *data);
1.210 -#endif
1.211 -
1.212 -/**
1.213 - * Makes a SSL connection using an already open file descriptor.
1.214 - *
1.215 - * @param account The account making the connection.
1.216 - * @param fd The file descriptor.
1.217 - * @param func The SSL input handler function.
1.218 - * @param error_func The SSL error handler function.
1.219 - * @param host The hostname of the other peer (to verify the CN)
1.220 - * @param data User-defined data.
1.221 - *
1.222 - * @return The SSL connection handle.
1.223 - *
1.224 - * @since 2.2.0
1.225 - */
1.226 -PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd,
1.227 - PurpleSslInputFunction func,
1.228 - PurpleSslErrorFunction error_func,
1.229 - const char *host,
1.230 - void *data);
1.231 -
1.232 -/**
1.233 - * Adds an input watcher for the specified SSL connection.
1.234 - * Once the SSL handshake is complete, use this to watch for actual data across it.
1.235 - *
1.236 - * @param gsc The SSL connection handle.
1.237 - * @param func The callback function.
1.238 - * @param data User-defined data.
1.239 - */
1.240 -void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func,
1.241 - void *data);
1.242 -
1.243 -/**
1.244 - * Closes a SSL connection.
1.245 - *
1.246 - * @param gsc The SSL connection to close.
1.247 - */
1.248 -void purple_ssl_close(PurpleSslConnection *gsc);
1.249 -
1.250 -/**
1.251 - * Reads data from an SSL connection.
1.252 - *
1.253 - * @param gsc The SSL connection handle.
1.254 - * @param buffer The destination buffer.
1.255 - * @param len The maximum number of bytes to read.
1.256 - *
1.257 - * @return The number of bytes read.
1.258 - */
1.259 -size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len);
1.260 -
1.261 -/**
1.262 - * Writes data to an SSL connection.
1.263 - *
1.264 - * @param gsc The SSL connection handle.
1.265 - * @param buffer The buffer to write.
1.266 - * @param len The length of the data to write.
1.267 - *
1.268 - * @return The number of bytes written.
1.269 - */
1.270 -size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len);
1.271 -
1.272 -/**
1.273 - * Obtains the peer's presented certificates
1.274 - *
1.275 - * @param gsc The SSL connection handle
1.276 - *
1.277 - * @return The peer certificate chain, in the order of certificate, issuer,
1.278 - * issuer's issuer, etc. @a NULL if no certificates have been provided,
1.279 - *
1.280 - * @since 2.2.0
1.281 - */
1.282 -GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc);
1.283 -
1.284 -/*@}*/
1.285 -
1.286 -/**************************************************************************/
1.287 -/** @name Subsystem API */
1.288 -/**************************************************************************/
1.289 -/*@{*/
1.290 -
1.291 -/**
1.292 - * Sets the current SSL operations structure.
1.293 - *
1.294 - * @param ops The SSL operations structure to assign.
1.295 - */
1.296 -void purple_ssl_set_ops(PurpleSslOps *ops);
1.297 -
1.298 -/**
1.299 - * Returns the current SSL operations structure.
1.300 - *
1.301 - * @return The SSL operations structure.
1.302 - */
1.303 -PurpleSslOps *purple_ssl_get_ops(void);
1.304 -
1.305 -/**
1.306 - * Initializes the SSL subsystem.
1.307 - */
1.308 -void purple_ssl_init(void);
1.309 -
1.310 -/**
1.311 - * Uninitializes the SSL subsystem.
1.312 - */
1.313 -void purple_ssl_uninit(void);
1.314 -
1.315 -/*@}*/
1.316 -
1.317 -#ifdef __cplusplus
1.318 -}
1.319 -#endif
1.320 -
1.321 -#endif /* _PURPLE_SSLCONN_H_ */