Added some (more) comments to .h files in lib/ and some minor fixes/cleanups.

1 files changed, 30 insertions, 0 deletions

diff --git a/lib/ssl_client.h b/lib/ssl_client.h
index 1a9c79e9..964caee4 100644
--- a/lib/ssl_client.h
+++ b/lib/ssl_client.h
@@ -23,20 +23,50 @@
   Suite 330, Boston, MA  02111-1307  USA
 */
 
+/* ssl_client makes it easier to open SSL connections to servers. (It
+   doesn't offer SSL server functionality yet, but it could be useful
+   to add it later.) Different ssl_client modules are available, and
+   ssl_client tries to make them all behave the same. It's very simple
+   and basic, it just imitates the proxy_connect() function from the
+   Gaim libs and passes the socket to the program once the handshake
+   is completed. */
+
 #include <glib.h>
 #include "proxy.h"
 
+/* Some generic error codes. Especially SSL_AGAIN is important if you
+   want to do asynchronous I/O. */
 #define SSL_OK            0
 #define SSL_NOHANDSHAKE   1
 #define SSL_AGAIN         2
 
 extern int ssl_errno;
 
+/* This is what your callback function should look like. */
 typedef gboolean (*ssl_input_function)(gpointer, void*, b_input_condition);
 
+
+/* Connect to host:port, call the given function when the connection is
+   ready to be used for SSL traffic. This is all done asynchronously, no
+   blocking I/O! (Except for the DNS lookups, for now...) */
 G_MODULE_EXPORT void *ssl_connect( char *host, int port, ssl_input_function func, gpointer data );
+
+/* Obviously you need special read/write functions to read data. */
 G_MODULE_EXPORT int ssl_read( void *conn, char *buf, int len );
 G_MODULE_EXPORT int ssl_write( void *conn, const char *buf, int len );
+
+/* Abort the SSL connection and disconnect the socket. Do not use close()
+   directly, both the SSL library and the peer will be unhappy! */
 G_MODULE_EXPORT void ssl_disconnect( void *conn_ );
+
+/* Get the fd for this connection, you will usually need it for event
+   handling. */
 G_MODULE_EXPORT int ssl_getfd( void *conn );
+
+/* This function returns GAIM_INPUT_READ/WRITE. With SSL connections it's
+   possible that something has to be read while actually were trying to
+   write something (think about key exchange/refresh/etc). So when an
+   SSL operation returned SSL_AGAIN, *always* use this function when
+   adding an event handler to the queue. (And it should perform exactly
+   the same action as the handler that just received the SSL_AGAIN.) */
 G_MODULE_EXPORT b_input_condition ssl_getdirection( void *conn );