pidgin3: comparison src/protocols/oscar/conn.c

-:0dbcd2937463
+:15b365a0a7fe
 /*
-* conn.c
+* Low-level connection handling.
 *
 * Does all this gloriously nifty connection handling stuff...
 *
 */
 #ifdef _WIN32
 #include "win32dep.h"
 #endif
-/*
+/**
 * In OSCAR, every connection has a set of SNAC groups associated
 * with it.  These are the groups that you can send over this connection
 * without being guaranteed a "Not supported" SNAC error.
 *
 * The grand theory of things says that these associations transcend
 	return;
 }
 /**
-* Clears out connection list, killing remaining connections.
+* Clears out the connection list, killing remaining connections.
 *
-* @param sess Session to be cleared
+* @param sess Session to be cleared.
 */
 static void aim_connrst(aim_session_t *sess)
 {
 	if (sess->connlist) {
 	return;
 }
 /**
-* Reset a connection to default values.
+* Initializes and/or resets a connection structure to the default values.
-* Initializes and/or resets a connection structure.
+*
-*
+* @param deadconn Connection to be reset.
-* @param deadconn Connection to be reset
 */
 static void aim_conn_init(aim_conn_t *deadconn)
 {
 	if (!deadconn)
 	return;
 }
 /**
-* aim_conn_getnext - Gets a new connection structure.
-*
 * Allocate a new empty connection structure.
 *
 * @param sess Session
-* @return Returns new connection structure
+* @return Returns the new connection structure.
 */
 static aim_conn_t *aim_conn_getnext(aim_session_t *sess)
 {
 	aim_conn_t *newconn;
 	return newconn;
 }
 /**
-* aim_conn_kill - Close and free a connection.
-*
 * Close, clear, and free a connection structure. Should never be
 * called from within libfaim.
 *
-* @param sess Session for the connection
+* @param sess Session for the connection.
-* @param deadconn Connection to be freed
+* @param deadconn Connection to be freed.
 */
 faim_export void aim_conn_kill(aim_session_t *sess, aim_conn_t **deadconn)
 {
 	aim_conn_t *cur, **prev;
 	return;
 }
 /**
-* aim_conn_close - Close a connection
-*
 * Close (but not free) a connection.
 *
 * This leaves everything untouched except for clearing the
 * handler list and setting the fd to -1 (used to recognize
 * dead connections).  It will also remove cookies if necessary.
 *
-* @param deadconn Connection to close
+* Why only if fd >= 3?  Seems rather implementation specific...
+* fd's do not have to be distributed in a particular order, do they?
+*
+* @param deadconn The connection to close.
 */
 faim_export void aim_conn_close(aim_conn_t *deadconn)
 {
 	aim_rxcallback_t userfunc;
 	return;
 }
 /**
-* aim_getconn_type - Find a connection of a specific type
+* Locates a connection of the specified type in the
-*
-* Searches for a connection of the specified type in the
 * specified session.
 *
-* XXX except for RENDEZVOUS, all uses of this should be removed and
+* XXX - Except for rendezvous, all uses of this should be removed and
-* use aim_conn_findbygroup() instead.
+* aim_conn_findbygroup() should be used instead.
 *
-* @param sess Session to search
+* @param sess The session to search.
-* @param type Type of connection to look for
+* @param type The type of connection to look for.
-* @return Returns the first connection found of target type
+* @return Returns the first connection found of the given target type,
+*         or NULL if none could be found.
 */
 faim_export aim_conn_t *aim_getconn_type(aim_session_t *sess, int type)
 {
 	aim_conn_t *cur;
 	return cur;
 }
 /**
-* aim_proxyconnect - An extrememly quick and dirty SOCKS5 interface.
+* Handle normal connections or SOCKS5 via an extrememly quick and
+* dirty SOCKS5 interface.
 *
 * Attempts to connect to the specified host via the configured
 * proxy settings, if present.  If no proxy is configured for
 * this session, the connection is done directly.
 *
-* XXX this is really awful.
+* XXX - this is really awful.
-*
+* XXX - Split the SOCKS5 and the normal connection stuff into two
-* @param sess Session to connect
+*        separate functions.
-* @param host Host to connect to
+*
-* @param port Port to connect to
+* @param sess Session to connect.
-* @param statusret Return value of the connection
+* @param host Host to connect to.
+* @param port Port to connect to.
+* @param statusret Return value of the connection.
 */
 static int aim_proxyconnect(aim_session_t *sess, const char *host, fu16_t port, fu32_t *statusret)
 {
 	int fd = -1;
 	}
 	return fd;
 }
 /**
-* aim_cloneconn - clone an aim_conn_t
+* Clone an aim_conn_t.
 *
 * A new connection is allocated, and the values are filled in
 * appropriately. Note that this function sets the new connnection's
 * ->priv pointer to be equal to that of its parent: only the pointer
 * is copied, not the data it points to.
 *
-* @param sess session containing parent
+* @param sess The session containing this connection.
-* @param src connection to clone
+* @param src The connection to clone.
-* @return Returns a pointer to the new aim_conn_t, or %NULL on error
+* @return Returns a pointer to the new aim_conn_t, or %NULL on error.
 */
 faim_internal aim_conn_t *aim_cloneconn(aim_session_t *sess, aim_conn_t *src)
 {
 	aim_conn_t *conn;
 	return conn;
 }
 /**
-* aim_newconn - Open a new connection
-*
 * Opens a new connection to the specified dest host of specified
 * type, using the proxy settings if available.  If @host is %NULL,
 * the connection is allocated and returned, but no connection
 * is made.
 *
 	return connstruct;
 }
 /**
-* aim_conngetmaxfd - Return the highest valued file discriptor in session
-*
-* @param sess Session to search
-* @return Returns the highest values file descriptor of
-*         all open connections in @sess
-*/
-faim_export int aim_conngetmaxfd(aim_session_t *sess)
-{
-	int j;
-	aim_conn_t *cur;
-	for (cur = sess->connlist, j = 0; cur; cur = cur->next) {
-		if (cur->fd > j)
-			j = cur->fd;
-	}
-	return j;
-}
-/**
-* aim_conn_in_sess - Predicate to test the presense of a connection in a sess
-*
 * Searches @sess for the passed connection.
 *
-* @param sess Session to look in
+* @param sess Session in which to look.
-* @param conn Connection to look for
+* @param conn Connection to look for.
-* @return Returns 1 if the passed connection is present, zero otherwise
+* @return Returns 1 if the passed connection is present, zero otherwise.
 */
 faim_export int aim_conn_in_sess(aim_session_t *sess, aim_conn_t *conn)
 {
 	aim_conn_t *cur;
 	return 0;
 }
 /**
-* aim_select - Wait for a socket with data or timeout
-*
 * Waits for a socket with data or for timeout, whichever comes first.
 * See select(2).
 *
 * Return codes in *status:
 *   -1  error in select() (%NULL returned)
 	return NULL;  /* no waiting or error, return */
 }
 /**
-* aim_conn_setlatency - Set a forced latency value for connection
+* Set a forced latency value for connection.  Basically causes
-*
+* @newval seconds to be spent between transmits on a connection.
-* Causes @newval seconds to be spent between transmits on a connection.
 *
 * This is my lame attempt at overcoming not understanding the rate
 * limiting.
 *
 * XXX: This should really be replaced with something that scales and
 * backs off like the real rate limiting does.
 *
-* @param conn Conn to set latency for
+* @param conn Conn to set latency for.
-* @param newval Number of seconds to force between transmits
+* @param newval Number of seconds to force between transmits.
-* @return Returns -1 if the connection does not exist, zero otherwise
+* @return Returns -1 if the connection does not exist, zero otherwise.
 */
 faim_export int aim_conn_setlatency(aim_conn_t *conn, int newval)
 {
 	if (!conn)
 	return 0;
 }
 /**
-* aim_setupproxy - Configure a proxy for this session
+* Configure a proxy for this session.
 *
 * Call this with your SOCKS5 proxy server parameters before
 * the first call to aim_newconn().  If called with all %NULL
 * args, it will clear out a previously set proxy.
 *
 * Set username and password to %NULL if not applicable.
 *
-* @param sess Session to set proxy for
+* @param sess Session to set proxy for.
-* @param server SOCKS server
+* @param server SOCKS server.
-* @param username SOCKS username
+* @param username SOCKS username.
-* @param password SOCKS password
+* @param password SOCKS password.
 */
 faim_export void aim_setupproxy(aim_session_t *sess, const char *server, const char *username, const char *password)
 {
 	/* clear out the proxy info */
 	if (!server || !strlen(server)) {
 	return;
 }
 /**
-* aim_session_kill - Deallocate a session
+* Logoff and deallocate a session.
 *
 * @param sess Session to kill
 */
 faim_export void aim_session_kill(aim_session_t *sess)
 {
 	return;
 }
 /**
-* aim_setdebuggingcb - Set the function to call when outputting debugging info
+* Set the function to call when outputting debugging info.
 *
 * The function specified is called whenever faimdprintf() is used within
 * libfaim, and the session's debugging level is greater tha nor equal to
 * the value faimdprintf was called with.
 *
-* @param sess Session to change
+* @param sess Session to change.
-* @param cb Function to call
+* @param cb Function to call.
-* @return Returns -1 if the session does not exist, zero otherwise
+* @return Returns -1 if the session does not exist, zero otherwise.
 */
 faim_export int aim_setdebuggingcb(aim_session_t *sess, faim_debugging_callback_t cb)
 {
 	if (!sess)
 	return 0;
 }
 /**
-* aim_conn_isconnecting - Determine if a connection is connecting
+* Determine if a connection is connecting.
 *
-* @param conn Connection to examine
+* @param conn Connection to examine.
 * @return Returns nonzero if the connection is in the process of
 *         connecting (or if it just completed and
 *         aim_conn_completeconnect() has yet to be called on it).
 */
 faim_export int aim_conn_isconnecting(aim_conn_t *conn)
 		return NULL;
 	return (aim_session_t *)conn->sessv;
 }
-/*
+/**
-* aim_logoff()
+* Close -ALL- open connections.
 *
-* Closes -ALL- open connections.
+* @param sess The session.
-*
+* @return Zero.
 */
 faim_export int aim_logoff(aim_session_t *sess)
 {
 	aim_connrst(sess);  /* in case we want to connect again */
 	return 0;
 }
-/*
+/**
-* aim_flap_nop()
+* No-op.  This sends an empty channel 5 SNAC.  WinAIM 4.x and higher
-*
+* sends these _every minute_ to keep the connection alive.
-* No-op.  WinAIM 4.x sends these _every minute_ to keep
-* the connection alive.
 */
 faim_export int aim_flap_nop(aim_session_t *sess, aim_conn_t *conn)
 {
 	aim_frame_t *fr;

Mercurial > pidgin3 / file comparison

comparison: src/protocols/oscar/conn.c

src/protocols/oscar/conn.c