mod-mcabber-jingle: comparison jingle/jingle.c

equal deleted inserted replaced

-:cd97a18dd0b9
+:efc92c939fef
 .uninit          = jingle_uninit,
 .next            = NULL,
 };
+/**
+* @brief Handle all incoming IQs containing a <jingle> node
+*/
 LmHandlerResult jingle_handle_iq(LmMessageHandler *handler,
 LmConnection *connection, LmMessage *message,
 gpointer user_data)
 {
 LmMessageSubType iqtype = lm_message_get_sub_type(message);
 jingle_free_jinglenode(jn);
 return LM_HANDLER_RESULT_REMOVE_MESSAGE;
 }
 /**
-* 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,
 LmMessage *message, gpointer user_data)
 {
 el = el->next;
 }
 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)
 	  ack_timeout_checker = g_timeout_add_seconds(3, jingle_ack_timeout_checker, NULL);
 return FALSE;
 }
 /**
+* @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.
 */
 void jingle_ack_iq(LmMessage *m)
 {
 lm_connection_send(lconnection, r, NULL);
 lm_message_unref(r);
 }
 /**
-* 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)
 {
 LmMessage *r;
 r = lm_message_new_iq_from_query(m, LM_MESSAGE_SUB_TYPE_ERROR);
 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);
 }
 return r;
 }
 /**
-* 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)
 {
 LmMessage *r = jingle_new_iq_error(m, errtype, cond, jinglecond);
 lm_connection_send(lconnection, r, NULL);
 }
 }
 /**
-* Find the best resource to initiate a jingle session.
+* @brief Find the best resource to initiate a jingle session with
-* Test every ressource for a given jid and return the one
+* @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[])
 {
 gchar *choosenres;
 guint indexns;
 return NULL;
 }
 /**
-* 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)
 {
 guint i, actstrlen = sizeof(jingle_action_list)/sizeof(jingle_action_list[0]);
 for (i = 0; i < actstrlen; i++)
 return JINGLE_UNKNOWN_ACTION;
 }
 /**
-* This function should not be called if jn->message was created
+* @brief Free a JingleNode struct
-* using lm_message_from_jinglenode because loudmouth strdup
+*
-* strings we insert as attributes. the pointers in the LmMessage
+* Since the JingleNode contains only pointers to the attributes
-* and the JingleNode would not refer to the same addresses and
+* and nodes of the LmMessage, we only have to unref the LmMessage
-* a call to lm_message_unref would not free the data from the
+* and free() the struct itself to destroy it.
-* JingleNode.
 */
 void jingle_free_jinglenode(JingleNode *jn)
 {
 g_slist_foreach(jn->content, (GFunc)g_free, NULL);
 g_slist_free(jn->content);
 lm_message_unref(jn->message);
 g_free(jn);
 }
+/**
+* @brief Unregister our IQ handler to loudmouth.
+*/
 static void jingle_unregister_lm_handlers(void)
 {
 if (lconnection) {
 lm_connection_unregister_message_handler(lconnection, jingle_iq_handler,
 LM_MESSAGE_TYPE_IQ);
 }
 }
+/**
+* @brief Register our IQ handler to loudmouth.
+*/
 static void jingle_register_lm_handlers(void)
 {
 jingle_unregister_lm_handlers();
 if (lconnection) {
 lm_connection_register_message_handler(lconnection, jingle_iq_handler,

changeset 144	efc92c939fef
parent 139	459b2503c1a3
child 151	b1acef78e4f5