Changeset 69cb623 for lib/ssl_client.h

Timestamp:

2006-10-15T09:41:12Z (18 years ago)

Author:

Wilmer van der Gaast <wilmer@…>

Branches:

master

Children:

2529faf

Parents:

695e392 (diff), e97827b (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merging with storage-xml. It seems to be working pretty well, so maybe
this way more people will test it. :-)

File:

• lib/ssl_client.h (moved) (moved from protocols/ssl_client.h) (2 diffs)

lib/ssl_client.h

@@ -24 +24 @@
 */
 
+/* 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
@@ -33 +43 @@
 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 );