--- a/jingle/check.c Tue Aug 17 23:14:52 2010 +0200
+++ b/jingle/check.c Tue Aug 17 23:30:53 2010 +0200
@@ -49,7 +49,13 @@
/**
- * Populate a jingle_data struct from a <jingle> element.
+ * @param message The incoming message
+ * @param node The <jingle> node in message
+ * @param jn The JingleNode to populate
+ * @param err A GError* to store the error
+ * @return TRUE if successfull, FALSE if an error happened
+ *
+ * Populate a JingleNode struct from a <jingle> element.
* Check if the element is in compliance with the XEP.
*/
gboolean check_jingle(LmMessage *message, LmMessageNode *node,
@@ -154,8 +160,11 @@
}
/**
- * Check <content> elements if there is any.
- * Add them to the JingleNode struct.
+ * @param jn The JingleNode to populate
+ * @param err A GError* to store the error
+ * @return TRUE if successfull, FALSE if an error happened
+ *
+ * Check all <content> element and add them to the JingleNode::content linked list.
*/
gboolean check_contents(JingleNode *jn, GError **err)
{
--- a/jingle/check.h Tue Aug 17 23:14:52 2010 +0200
+++ b/jingle/check.h Tue Aug 17 23:30:53 2010 +0200
@@ -1,3 +1,10 @@
+/**
+ * @file check.h
+ * @brief check.c header file
+ * @author Nicolas Cornu
+ * @version 0.1
+ */
+
#ifndef __JINGLE_CHECK_H__
#define __JINGLE_CHECK_H__ 1
@@ -20,8 +27,6 @@
JingleNode *jn, GError **err);
gboolean check_contents(JingleNode *jn, GError **err);
-gboolean check_transport(const gchar *xmlns, gconstpointer *data);
-
GQuark jingle_check_error_quark(void);
#endif
--- a/jingle/jingle.c Tue Aug 17 23:14:52 2010 +0200
+++ b/jingle/jingle.c Tue Aug 17 23:30:53 2010 +0200
@@ -90,6 +90,9 @@
};
+/**
+ * @brief Handle all incoming IQs containing a <jingle> node
+ */
LmHandlerResult jingle_handle_iq(LmMessageHandler *handler,
LmConnection *connection, LmMessage *message,
gpointer user_data)
@@ -139,7 +142,7 @@
}
/**
- * Handle incoming ack iq (type result or error).
+ * @brief Handle incoming ack iq (type result or error).
*/
LmHandlerResult jingle_handle_ack_iq(LmMessageHandler *handler,
LmConnection *connection,
@@ -183,6 +186,14 @@
return TRUE;
}
+/**
+ * @param ah A JingleAckHandle struct
+ * @return The LmMessageHandler to use when sending a message
+ * with lm_connection_send_with_reply
+ *
+ * jingle_new_ack_handler allow to easily create new LmMessageHandler to
+ * be called back when a message we sent was acknowledged by its recipient.
+ */
LmMessageHandler *jingle_new_ack_handler(JingleAckHandle *ah)
{
if(ack_timeout_checker == 0)
@@ -248,9 +259,12 @@
}
/**
+ * @brief Acknowledge the receipt of a message.
+ * @param m The LmMessage to ack
+ *
* According to the specifications:
* "An entity that receives an IQ request of type "get" or "set" MUST
- * reply with an IQ response of type "result" or "error"."
+ * reply with an IQ response of type "result" or "error"."\n
* For Jingle's IQ, we have to reply with an empty "result" IQ to acknowledge
* receipt.
*/
@@ -264,7 +278,18 @@
}
/**
- * Create an error IQ.
+ * @brief Create a new jingle IQ with an error.
+ * @param m The message to reply to
+ * @param errtype The error type (the type attribute of <error>)
+ * @param cond The error condition
+ * @param jinglecond The jingle error condition
+ *
+ * Error types are defined <a href="http://tools.ietf.org/html/
+ * draft-ietf-xmpp-3920bis-12#section-8.3.2">section 8.3.2 of RFC 3920bis</a>.\n
+ * Error conditions are defined <a href="http://tools.ietf.org/html/
+ * draft-ietf-xmpp-3920bis-12#section-8.3.3">section 8.3.3 of RFC 3920bis</a>.\n
+ * Jingle Error conditions are defined <a href="http://xmpp.org/extensions/
+ * xep-0166.html#errors">section 10 of XEP-0166</a>.
*/
LmMessage *jingle_new_iq_error(LmMessage *m, const gchar *errtype,
const gchar *cond, const gchar *jinglecond)
@@ -276,13 +301,11 @@
err = lm_message_node_add_child(r->node, "error", NULL);
lm_message_node_set_attribute(err, "type", errtype);
- // error condition as defined by RFC 3920bis section 8.3.3
if (cond != NULL) {
tmpnode = lm_message_node_add_child(err, cond, NULL);
lm_message_node_set_attribute(tmpnode, "xmlns", NS_XMPP_STANZAS);
}
- // jingle error condition as defined by XEP-0166 section 10
if (jinglecond != NULL) {
tmpnode = lm_message_node_add_child(err, jinglecond, NULL);
lm_message_node_set_attribute(tmpnode, "xmlns", NS_JINGLE_ERRORS);
@@ -292,7 +315,13 @@
}
/**
- * Reply to a Jingle IQ with an error.
+ * @brief Reply to a jingle IQ with an error
+ * @param m The message to reply to
+ * @param errtype The error type (the type attribute of <error>)
+ * @param cond The error condition
+ * @param jinglecond The jingle error condition
+ *
+ * Use jingle_new_iq_error internally to generate a LmMessage.
*/
void jingle_send_iq_error(LmMessage *m, const gchar *errtype,
const gchar *cond, const gchar *jinglecond)
@@ -304,9 +333,15 @@
}
/**
- * Find the best resource to initiate a jingle session.
- * Test every ressource for a given jid and return the one
+ * @brief Find the best resource to initiate a jingle session with
+ * @param jid The jid of the buddy
+ * @param ns The an array of namespaces we are looking for
+ * @return A ressource supporting all namespaces in ns or NULL
+ * if we couldn't find any
+ *
+ * Test every ressource for the given jid and return the one
* who support all namespaces in ns.
+ * Note that you should free the string returned by this function.
*/
gchar *jingle_find_compatible_res(const gchar *jid, const gchar *ns[])
{
@@ -336,7 +371,10 @@
}
/**
- * Find the jingle_action corresponding to a string
+ * @brief Find the JingleAction corresponding to a string
+ * @param string The string to lockup
+ * @return The #JingleAction or JINGLE_UNKNOWN_ACTION if
+ * string is not a jingle action
*/
JingleAction jingle_action_from_str(const gchar *string)
{
@@ -349,12 +387,11 @@
}
/**
- * This function should not be called if jn->message was created
- * using lm_message_from_jinglenode because loudmouth strdup
- * strings we insert as attributes. the pointers in the LmMessage
- * and the JingleNode would not refer to the same addresses and
- * a call to lm_message_unref would not free the data from the
- * JingleNode.
+ * @brief Free a JingleNode struct
+ *
+ * Since the JingleNode contains only pointers to the attributes
+ * and nodes of the LmMessage, we only have to unref the LmMessage
+ * and free() the struct itself to destroy it.
*/
void jingle_free_jinglenode(JingleNode *jn)
{
@@ -364,6 +401,9 @@
g_free(jn);
}
+/**
+ * @brief Unregister our IQ handler to loudmouth.
+ */
static void jingle_unregister_lm_handlers(void)
{
if (lconnection) {
@@ -372,6 +412,9 @@
}
}
+/**
+ * @brief Register our IQ handler to loudmouth.
+ */
static void jingle_register_lm_handlers(void)
{
jingle_unregister_lm_handlers();
--- a/jingle/jingle.h Tue Aug 17 23:14:52 2010 +0200
+++ b/jingle/jingle.h Tue Aug 17 23:30:53 2010 +0200
@@ -1,23 +1,25 @@
+/**
+ * @file jingle.h
+ * @brief jingle.c header file
+ * @author Nicolas Cornu
+ * @version 0.1
+ */
+
#ifndef __JINGLE_H__
#define __JINGLE_H__ 1
-/**
- * \file jingle.h
- * \brief
- * \author Nicolas Cornu
- * \version 0.1
- */
-
#include <glib.h>
#include <loudmouth/loudmouth.h>
+/** Jingle namespace */
#define NS_JINGLE "urn:xmpp:jingle:1"
+/** Jingle Errors namespace */
#define NS_JINGLE_ERRORS "urn:xmpp:jingle:errors:1"
/**
- * \enum JingleAction
- * \brief Jingle actions constants
+ * @enum JingleAction
+ * @brief Jingle actions constants
*/
typedef enum {
JINGLE_UNKNOWN_ACTION,
@@ -50,48 +52,77 @@
JINGLE_SENDERS_RESPONDER,
} JingleSenders;
+/**
+ * @struct JingleNode
+ * @brief Represent an incoming jingle IQ
+ *
+ * This struct is used to represent an incoming jingle IQ.
+ * It should be destroyed as soon as it is not needed using #jingle_free_jinglenode
+ */
typedef struct {
- /* pointer to the original LmMessage */
+ /**
+ * @brief Pointer to the original LmMessage
+ */
LmMessage *message;
- /* pointer to the <jingle> element */
+ /**
+ * @brief Pointer to the <jingle> element
+ */
LmMessageNode *node;
- /* action attribute */
+ /**
+ * @brief Jingle action of the incoming IQ
+ */
JingleAction action;
- /* full JID of the entity that has initiated the session flow.
- * may be different from the 'from' address on the IQ-set of the
+ /**
+ * @brief Full JID of the entity that has initiated the session flow
+ *
+ * May be different from the 'from' address on the IQ-set of the
* session-initiate message.
- * recommended for session-initiate, not recommended otherwise. */
+ * recommended for session-initiate, not recommended otherwise.
+ */
const gchar *initiator;
- /* full JID of the entity that has replied to the initation.
- * can be different from the 'to' address on the IQ-set.
- * recommended for session-accept, not recommended otherwise. */
+ /**
+ * @brief Full JID of the entity that has replied to the initation.
+ *
+ * Can be different from the 'to' address on the IQ-set.
+ * recommended for session-accept, not recommended otherwise.
+ */
const gchar *responder;
- /* Random session identifier generated by the initator. */
+ /**
+ * @brief Random session identifier generated by the initator
+ */
const gchar *sid;
- /* Linked list of JingleContent. */
+ /**
+ * @brief Linked list of JingleContent.
+ */
GSList *content;
} JingleNode;
+/**
+ * @struct JingleContent
+ * @brief Struct used to represent a <content> element of an incoming Jingle IQ
+ */
typedef struct {
/**
- * pointer to the <content> element
+ * @brief pointer to the <content> element
*/
LmMessageNode *node;
- /** which party originally generated the content type.
+ /**
+ * which party originally generated the content type.
* the defined values are "initiator" and "responder"
* (where the default is "initiator"). required.
*/
JingleCreator creator;
- /** how the content definition is to be interpreted by the recipient.
+ /**
+ * how the content definition is to be interpreted by the recipient.
* optional, the default value is "session".
*/
const gchar *disposition; // optional, default=session
@@ -125,6 +156,12 @@
LmMessageNode *transport;
} JingleContent;
+/**
+ * @struct JingleActionList
+ *
+ * Represent a jingle action and the "handler"
+ * (defined in action-handlers.c) for that action.
+ */
struct JingleActionList {
const gchar *name;
void (*handler)(JingleNode *);
@@ -155,7 +192,7 @@
guint timeout;
/**
- * \private
+ * @private
*
* date at which the handler was inserted using
* jingle_new_ack_handler
@@ -163,7 +200,7 @@
time_t _inserted;
/**
- * \private
+ * @private
*
* a pointer to the LmMessageHandler created
* using jingle_new_ack_handler