[svn-commits] mmichelson: branch mmichelson/pool_shark2 r381590 - /team/mmichelson/pool_sha...

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Fri Feb 15 16:03:29 2013
New Revision: 381590

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=381590
Log:
Add doxygen for new functions added to res_sip API


Modified:
    team/mmichelson/pool_shark2/include/asterisk/res_sip.h

Modified: team/mmichelson/pool_shark2/include/asterisk/res_sip.h
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/pool_shark2/include/asterisk/res_sip.h?view=diff&rev=381590&r1=381589&r2=381590
==============================================================================
--- team/mmichelson/pool_shark2/include/asterisk/res_sip.h (original)
+++ team/mmichelson/pool_shark2/include/asterisk/res_sip.h Fri Feb 15 16:03:29 2013
@@ -451,6 +451,17 @@
  */
 int ast_sip_initialize_sorcery_auth(struct ast_sorcery *sorcery);
 
+/*!
+ * \brief Initialize the distributor module
+ *
+ * The distributor module is responsible for taking an incoming
+ * SIP message and placing it into the threadpool. Once in the threadpool,
+ * the distributor will perform endpoint lookups and authentication, and
+ * then distribute the message up the stack to any further modules.
+ *
+ * \retval -1 Failure
+ * \retval 0 Success
+ */
 int ast_sip_initialize_distributor(void);
 
 /*!
@@ -701,8 +712,44 @@
  */
 void ast_copy_pj_str(char *dest, pj_str_t *src, size_t size);
 
+/*!
+ * \brief Get the looked-up endpoint on an out-of dialog request or response
+ *
+ * The function may ONLY be called on out-of-dialog requests or responses. For
+ * in-dialog requests and responses, it is required that the user of the dialog
+ * has the looked-up endpoint stored locally.
+ *
+ * This function should never return NULL if the message is out-of-dialog. It will
+ * always return NULL if the message is in-dialog.
+ *
+ * \param rdata Out-of-dialog request or response
+ * \return The looked up endpoint
+ */
 struct ast_sip_endpoint *ast_pjsip_rdata_get_endpoint(pjsip_rx_data *rdata);
+
+/*!
+ * \brief Clone a pjsip_rx_data structure
+ *
+ * This is a wrapper around pjsip_rx_data_clone(). The difference
+ * is that this also attempts to copy mod_data from the original
+ * rdata.
+ *
+ * This version should always be called by modules that are at priority
+ * PJSIP_MOD_PRIORITY_DIALOG_USAGE or higher.
+ * \param rdata The rdata to clone
+ * \retval NULL Failure to copy
+ * \retval non-NULL The cloned rdata
+ */
 pjsip_rx_data *ast_pjsip_rx_data_clone(pjsip_rx_data *rdata);
+
+/*!
+ * \brief Free a cloned rdata structure
+ *
+ * Use this to free a pjsip_rx_data that was created via the
+ * \ref ast_pjsip_rx_data_clone function.
+ *
+ * \param rdata The cloned rdata to free
+ */
 void ast_pjsip_rx_data_free_cloned(pjsip_rx_data *rdata);
 
 #endif /* _RES_SIP_H */