--- a/src/irc_conn.h	Sun Mar 01 02:02:48 2009 +0200
+++ b/src/irc_conn.h	Sun Mar 08 17:17:37 2009 +0200
@@ -1,18 +1,25 @@
 #ifndef IRC_CONN_H
 #define IRC_CONN_H
 
-/*
- * Per-connection IRC setup and state/protocol handling.
+/**
+ * @file
+ *
+ * Support for connections to IRC servers, a rather fundamental thing. This holds the line_proto to handle the network
+ * communications, and then takes care of sending/receiving commands, as well as updating some core state like
+ * current nickname.
  */
 
+struct irc_conn;
+
+#include "error.h"
 #include "sock.h"
 #include "line_proto.h"
 #include "irc_line.h"
-#include "error.h"
+#include "irc_cmd.h"
 #include <stdbool.h>
 
 /*
- * A connection to an IRC server.
+ * Connection state
  */
 struct irc_conn {
     /* We are a line-based protocol */
@@ -20,6 +27,9 @@
 
     /* Registered (as in, we have a working nickname)? */
     bool registered;
+
+    /* Command handlers */
+    STAILQ_HEAD(irc_conn_handlers, irc_cmd_chain) handlers;
 };
 
 // XXX: this should probably be slightly reworked
@@ -34,16 +44,31 @@
     const char *realname;
 };
 
-/*
+/**
  * Create a new irc_conn using the given sock_stream, which should be connected to an IRC server. The parameters given
  * in \a config will be used to identify with the IRC server.
  *
  * On success, the resulting irc_conn is returned via *conn with SUCCESS. Otherwise, -ERR_* and error info is returned
  * via *err.
+ *
+ * @param conn the new irc_conn structure is returned via this pointer
+ * @param sock the socket connected to the IRC server
+ * @param config the basic information used to register
+ * @param err errors are returned via this pointer
+ * @return error code
  */
 err_t irc_conn_create (struct irc_conn **conn, struct sock_stream *sock, const struct irc_conn_config *config, struct error_info *err);
 
 /**
+ * Add a new chain of command handler callbacks to be used to handle irc_lines from the server. The given arg will be
+ * passed to the callbacks as the context argument. The chain will be appended to the end of the current list of chains.
+ *
+ * @param chain the array of irc_cmd_handler structs, terminated with a NULL entry
+ * @param arg the context argument to use for the callbacks
+ */
+err_t irc_conn_register_handler_chain (struct irc_conn *conn, struct irc_cmd_handler *handlers, void *arg);
+
+/**
  * @group Simple request functions
  *
  * The error handling of these functions is such that the error return code is can be used or ignored as convenient,
@@ -52,26 +77,46 @@
  * @{
  */
 
-/*
+/**
  * Send a generic IRC message
+ *
+ * @param conn the IRC protocol connection
+ * @param line the irc_line protocol line to send
+ * @return error code
  */
 err_t irc_conn_send (struct irc_conn *conn, const struct irc_line *line);
 
-/*
+/**
  * Send a NICK message
+ *
+ * @param nickname the new nickname to use
  */
 err_t irc_conn_NICK (struct irc_conn *conn, const char *nickname);
 
 /*
  * Send a USER message
+ *
+ * @param username the username to register with, may be replaced with ident reply
+ * @param realname the full-name to register with
  */
 err_t irc_conn_USER (struct irc_conn *conn, const char *username, const char *realname);
 
 /*
  * Send a PONG message to the given target
+ *
+ * @param target the PING source, aka. the target to send the PONG reply to
  */
 err_t irc_conn_PONG (struct irc_conn *conn, const char *target);
 
+/*
+ * Send a JOIN message for the given channel
+ *
+ * XXX: this doesn't implement the full command options
+ *
+ * @param channel the full channel name to join
+ */
+err_t irc_conn_JOIN (struct irc_conn *conn, const char *channel);
+
 // @}
 
 #endif /* IRC_CONN_H */