[svn-commits] russell: branch russell/chan_refcount r82459 - /team/russell/chan_refcount/in...

[SVN commits to the Digium repositories]

Author: russell
Date: Fri Sep 14 16:43:35 2007
New Revision: 82459

URL: http://svn.digium.com/view/asterisk?view=rev&rev=82459
Log:
Update documentation of various functions that take channels as arguments,
noting whether or not they expect the channel to be locked.  This is going to
be a lot of work, as it seems to be kind of random right now, but I'm going
to document the situation for each as I update various bits of code.

Modified:
    team/russell/chan_refcount/include/asterisk/channel.h
    team/russell/chan_refcount/include/asterisk/pbx.h

Modified: team/russell/chan_refcount/include/asterisk/channel.h
URL: http://svn.digium.com/view/asterisk/team/russell/chan_refcount/include/asterisk/channel.h?view=diff&rev=82459&r1=82458&r2=82459
==============================================================================
--- team/russell/chan_refcount/include/asterisk/channel.h (original)
+++ team/russell/chan_refcount/include/asterisk/channel.h Fri Sep 14 16:43:35 2007
@@ -760,11 +760,18 @@
  */
 int ast_hangup(struct ast_channel *chan);
 
-/*! \brief Softly hangup up a channel 
+/*! 
+ * \brief Softly hangup up a channel 
+ *
  * \param chan channel to be soft-hung-up
- * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
+ * \param cause	Ast hangupcause for hangup
+ *
+ * Call the protocol layer, but don't destroy the channel structure 
+ * (use this if you are trying to
  * safely hangup a channel managed by another thread.
- * \param cause	Ast hangupcause for hangup
+ *
+ * \note The channel passed to this function does not need to be locked.
+ *
  * \return Returns 0 regardless
  */
 int ast_softhangup(struct ast_channel *chan, int cause);
@@ -793,9 +800,16 @@
 int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset);
 
 /*! \brief Set when to hang a channel up 
+ *
  * \param chan channel on which to check for hang up
  * \param offset offset in seconds from current time of when to hang up
+ *
  * This function sets the absolute time out on a channel (when to hang up).
+ *
+ * \note This function does not require that the channel is locked before
+ *       calling it.
+ *
+ * \return Nothing
  */
 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
 
@@ -952,11 +966,18 @@
  */
 int ast_set_write_format(struct ast_channel *chan, int format);
 
-/*! \brief Sends text to a channel 
- * Write text to a display on a channel
+/*! 
+ * \brief Sends text to a channel 
+ *
  * \param chan channel to act upon
  * \param text string of text to send on the channel
- * \return Returns 0 on success, -1 on failure
+ *
+ * Write text to a display on a channel
+ *
+ * \note The channel must be locked before calling this function.
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_sendtext(struct ast_channel *chan, const char *text);
 

Modified: team/russell/chan_refcount/include/asterisk/pbx.h
URL: http://svn.digium.com/view/asterisk/team/russell/chan_refcount/include/asterisk/pbx.h?view=diff&rev=82459&r1=82458&r2=82459
==============================================================================
--- team/russell/chan_refcount/include/asterisk/pbx.h (original)
+++ team/russell/chan_refcount/include/asterisk/pbx.h Fri Sep 14 16:43:35 2007
@@ -836,8 +836,30 @@
 int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **buf);
 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
 void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
+
+/*!
+ * \brief Set a variable
+ *
+ * \param chan if non-NULL, set a channel variable, otherwise set a global variable
+ *
+ * \note If the chan argument is not NULL, it must be locked before calling this function.
+ *
+ * \return Nothing
+ */
 void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
+
+/*!
+ * \brief Retrieve a variable
+ *
+ * \param chan if non-NULL, retrieve a channel variable, otherwise retrieve 
+ *             a global variable
+ *
+ * \note If the chan argument is not NULL, it must be locked before calling this function.
+ *
+ * \return Nothing
+ */
 void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
+
 void pbx_builtin_clear_globals(void);
 int pbx_builtin_setvar(struct ast_channel *chan, void *data);
 void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
@@ -886,6 +908,8 @@
  * \param len the number of bytes in workspace
  *
  * This application executes a function in read mode on a given channel.
+ *
+ * \note The chan argument should not be locked when calling this function.
  *
  * \return zero on success, non-zero on failure
  */