--- a/libpurple/sslconn.h Sat Feb 01 02:32:30 2014 +0530
+++ b/libpurple/sslconn.h Sat Feb 01 17:27:24 2014 +0530
@@ -26,7 +26,11 @@
#ifndef _PURPLE_SSLCONN_H_
#define _PURPLE_SSLCONN_H_
-/** Possible SSL errors. */
+/**
+ * PurpleSslErrorType:
+ *
+ * Possible SSL errors.
+ */
typedef enum
{
PURPLE_SSL_HANDSHAKE_FAILED = 1,
@@ -39,7 +43,6 @@
#define PURPLE_SSL_DEFAULT_PORT 443
-/** @copydoc _PurpleSslConnection */
typedef struct _PurpleSslConnection PurpleSslConnection;
typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
@@ -47,39 +50,45 @@
typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *, PurpleSslErrorType,
gpointer);
+/**
+ * PurpleSslConnection:
+ * @host: Hostname to which the SSL connection will be made
+ * @port: Port to connect to
+ * @connect_cb_data: Data to pass to PurpleSslConnection::connect_cb()
+ * @connect_cb: Callback triggered once the SSL handshake is complete
+ * @error_cb: Callback triggered if there is an error during connection
+ * @recv_cb_data: Data passed to PurpleSslConnection::recv_cb()
+ * @recv_cb: User-defined callback executed when the SSL connection
+ * receives data
+ * @fd: File descriptor used to refer to the socket
+ * @inpa: Glib event source ID; used to refer to the received data
+ * callback in the glib eventloop
+ * @connect_data: Data related to the underlying TCP connection
+ * @private_data: Internal connection data managed by the SSL backend
+ * (GnuTLS/LibNSS/whatever)
+ * @verifier: Verifier to use in authenticating the peer
+ */
struct _PurpleSslConnection
{
- /** Hostname to which the SSL connection will be made */
char *host;
- /** Port to connect to */
int port;
- /** Data to pass to PurpleSslConnection::connect_cb() */
void *connect_cb_data;
- /** Callback triggered once the SSL handshake is complete */
PurpleSslInputFunction connect_cb;
- /** Callback triggered if there is an error during connection */
PurpleSslErrorFunction error_cb;
- /** Data passed to PurpleSslConnection::recv_cb() */
void *recv_cb_data;
- /** User-defined callback executed when the SSL connection receives data */
PurpleSslInputFunction recv_cb;
- /** File descriptor used to refer to the socket */
int fd;
- /** Glib event source ID; used to refer to the received data callback
- * in the glib eventloop */
guint inpa;
- /** Data related to the underlying TCP connection */
PurpleProxyConnectData *connect_data;
- /** Internal connection data managed by the SSL backend (GnuTLS/LibNSS/whatever) */
void *private_data;
-
- /** Verifier to use in authenticating the peer */
PurpleCertificateVerifier *verifier;
};
/**
+ * PurpleSslOps:
+ *
* SSL implementation operations structure.
*
* Every SSL implementation must provide all of these and register it via purple_ssl_set_ops()
@@ -88,7 +97,7 @@
typedef struct
{
/** Initializes the SSL system provided.
- * Returns: @a TRUE if initialization succeeded
+ * Returns: %TRUE if initialization succeeded
* @see purple_ssl_init
*/
gboolean (*init)(void);
@@ -110,8 +119,8 @@
* @gsc: Connection context
* @data: Pointer to buffer to drop data into
* @len: Maximum number of bytes to read
- * Returns: Number of bytes actually written into @a data (which may be
- * less than @a len), or <0 on error
+ * Returns: Number of bytes actually written into @data (which may be
+ * less than @len), or <0 on error
* @see purple_ssl_read
*/
size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len);
@@ -119,8 +128,8 @@
* @gsc: Connection context
* @data: Data buffer to send data from
* @len: Number of bytes to send from buffer
- * Returns: The number of bytes written to @a data (may be less than
- * @a len) or <0 on error
+ * Returns: The number of bytes written to @data (may be less than
+ * @len) or <0 on error
* @see purple_ssl_write
*/
size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len);
@@ -150,25 +159,26 @@
/*@{*/
/**
+ * purple_ssl_is_supported:
+ *
* Returns whether or not SSL is currently supported.
*
- * Returns: @a TRUE if SSL is supported, or @a FALSE otherwise.
+ * Returns: %TRUE if SSL is supported, or %FALSE otherwise.
*/
gboolean purple_ssl_is_supported(void);
/**
+ * purple_ssl_strerror:
+ * @error: Error code
+ *
* Returns a human-readable string for an SSL error.
*
- * @error: Error code
* Returns: Human-readable error explanation
*/
const gchar * purple_ssl_strerror(PurpleSslErrorType error);
/**
- * Makes a SSL connection to the specified host and port. The caller
- * should keep track of the returned value and use it to cancel the
- * connection, if needed.
- *
+ * purple_ssl_connect:
* @account: The account making the connection.
* @host: The destination host.
* @port: The destination port.
@@ -179,6 +189,10 @@
* destroyed for you.
* @data: User-defined data.
*
+ * Makes a SSL connection to the specified host and port. The caller
+ * should keep track of the returned value and use it to cancel the
+ * connection, if needed.
+ *
* Returns: The SSL connection handle.
*/
PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host,
@@ -187,10 +201,7 @@
void *data);
/**
- * Makes a SSL connection to the specified host and port, using the separate
- * name to verify with the certificate. The caller should keep track of the
- * returned value and use it to cancel the connection, if needed.
- *
+ * purple_ssl_connect_with_ssl_cn:
* @account: The account making the connection.
* @host: The destination host.
* @port: The destination port.
@@ -202,6 +213,10 @@
* @ssl_host: The hostname of the other peer (to verify the CN)
* @data: User-defined data.
*
+ * Makes a SSL connection to the specified host and port, using the separate
+ * name to verify with the certificate. The caller should keep track of the
+ * returned value and use it to cancel the connection, if needed.
+ *
* Returns: The SSL connection handle.
*/
PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host,
@@ -211,8 +226,7 @@
void *data);
/**
- * Makes a SSL connection using an already open file descriptor.
- *
+ * purple_ssl_connect_with_host_fd:
* @account: The account making the connection.
* @fd: The file descriptor.
* @func: The SSL input handler function.
@@ -220,6 +234,8 @@
* @host: The hostname of the other peer (to verify the CN)
* @data: User-defined data.
*
+ * Makes a SSL connection using an already open file descriptor.
+ *
* Returns: The SSL connection handle.
*/
PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd,
@@ -229,62 +245,68 @@
void *data);
/**
- * Adds an input watcher for the specified SSL connection.
- * Once the SSL handshake is complete, use this to watch for actual data across it.
- *
+ * purple_ssl_input_add:
* @gsc: The SSL connection handle.
* @func: The callback function.
* @data: User-defined data.
+ *
+ * Adds an input watcher for the specified SSL connection.
+ * Once the SSL handshake is complete, use this to watch for actual data across it.
*/
void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func,
void *data);
/**
+ * purple_ssl_input_remove:
+ * @gsc: The SSL connection handle.
+ *
* Removes an input watcher, added with purple_ssl_input_add().
*
* If there is no input watcher set, does nothing.
- *
- * @gsc: The SSL connection handle.
*/
void
purple_ssl_input_remove(PurpleSslConnection *gsc);
/**
- * Closes a SSL connection.
+ * purple_ssl_close:
+ * @gsc: The SSL connection to close.
*
- * @gsc: The SSL connection to close.
+ * Closes a SSL connection.
*/
void purple_ssl_close(PurpleSslConnection *gsc);
/**
- * Reads data from an SSL connection.
- *
+ * purple_ssl_read:
* @gsc: The SSL connection handle.
* @buffer: The destination buffer.
* @len: The maximum number of bytes to read.
*
+ * Reads data from an SSL connection.
+ *
* Returns: The number of bytes read.
*/
size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len);
/**
- * Writes data to an SSL connection.
- *
+ * purple_ssl_write:
* @gsc: The SSL connection handle.
* @buffer: The buffer to write.
* @len: The length of the data to write.
*
+ * Writes data to an SSL connection.
+ *
* Returns: The number of bytes written.
*/
size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len);
/**
+ * purple_ssl_get_peer_certificates:
+ * @gsc: The SSL connection handle
+ *
* Obtains the peer's presented certificates
*
- * @gsc: The SSL connection handle
- *
* Returns: The peer certificate chain, in the order of certificate, issuer,
- * issuer's issuer, etc. @a NULL if no certificates have been provided,
+ * issuer's issuer, etc. %NULL if no certificates have been provided,
*/
GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc);
@@ -296,13 +318,16 @@
/*@{*/
/**
- * Sets the current SSL operations structure.
+ * purple_ssl_set_ops:
+ * @ops: The SSL operations structure to assign.
*
- * @ops: The SSL operations structure to assign.
+ * Sets the current SSL operations structure.
*/
void purple_ssl_set_ops(PurpleSslOps *ops);
/**
+ * purple_ssl_get_ops:
+ *
* Returns the current SSL operations structure.
*
* Returns: The SSL operations structure.
@@ -310,11 +335,15 @@
PurpleSslOps *purple_ssl_get_ops(void);
/**
+ * purple_ssl_init:
+ *
* Initializes the SSL subsystem.
*/
void purple_ssl_init(void);
/**
+ * purple_ssl_uninit:
+ *
* Uninitializes the SSL subsystem.
*/
void purple_ssl_uninit(void);