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

[SVN commits to the Digium repositories]

Author: russell
Date: Thu Dec 27 15:18:37 2007
New Revision: 95022

URL: http://svn.digium.com/view/asterisk?view=rev&rev=95022
Log:
document the channel iterator functions

Modified:
    team/russell/chan_refcount/include/asterisk/channel.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=95022&r1=95021&r2=95022
==============================================================================
--- team/russell/chan_refcount/include/asterisk/channel.h (original)
+++ team/russell/chan_refcount/include/asterisk/channel.h Thu Dec 27 15:18:37 2007
@@ -1588,24 +1588,89 @@
 	return NULL;
 }
 
-/* 
+/*! Channel Iterating @{ */
+
+/*!
  * \brief A channel iterator
  *
  * This is an opaque type.
  */
 struct ast_channel_iterator;
 
+/*!
+ * \brief Destroy a channel iterator
+ *
+ * \arg i the itereator to destroy
+ *
+ * This function is used to destroy a channel iterator that was retrieved by
+ * using one of the channel_iterator_new() functions.
+ *
+ * \return NULL, for convenience to clear out the pointer to the iterator that
+ * was just destroyed.
+ */
 struct ast_channel_iterator *ast_channel_iterator_destroy(struct ast_channel_iterator *i);
 
+/*!
+ * \brief Create a new channel iterator based on extension
+ *
+ * \arg exten The extension that channels must be in
+ * \arg context The context that channels must be in (optional)
+ *
+ * After creating an iterator using this function, the ast_channel_iterator_next()
+ * function can be used to iterate through all channels that are currently
+ * in the specified context and extension.
+ *
+ * \retval NULL on failure
+ * \retval a new channel iterator based on the specified parameters
+ */
 struct ast_channel_iterator *ast_channel_iterator_by_exten_new(const char *exten, 
 	const char *context);
 
+/*!
+ * \brief Create a new channel iterator based on name
+ *
+ * \arg name channel name to match
+ * \arg name_len number of characters in the channel name to match on.  This
+ *      would be used to match based on name prefix.  If matching on the full
+ *      channel name is desired, then this parameter should be 0.
+ *
+ * After creating an iterator using this function, the ast_channel_iterator_next()
+ * function can be used to iterate through all channels that exist that have
+ * the specified name or name prefix.
+ *
+ * \retval NULL on failure
+ * \retval a new channel iterator based on the specified parameters
+ */
 struct ast_channel_iterator *ast_channel_iterator_by_name_new(const char *name, 
 	size_t name_len);
 
+/*!
+ * \brief Create a new channel iterator
+ *
+ * After creating an iterator using this function, the ast_channel_iterator_next()
+ * function can be used to iterate through all channels that exist.
+ *
+ * \retval NULL on failure
+ * \retval a new channel iterator
+ */
 struct ast_channel_iterator *ast_channel_iterator_all_new(void);
 
+/*!
+ * \brief Get the next channel for a channel iterator
+ *
+ * \arg i the channel iterator that was created using one of the
+ *  channel_iterator_new() functions.
+ *
+ * This function should be used to iterate through all channels that match a
+ * specified set of parameters that were provided when the iterator was created.
+ *
+ * \retval the next channel that matches the parameters used when the iterator
+ *         was created.
+ * \retval NULL, if no more channels match the iterator parameters.
+ */
 struct ast_channel *ast_channel_iterator_next(struct ast_channel_iterator *i);
+
+/*! @} End channel iterator definitions. */
 
 
 /*!
@@ -1616,6 +1681,9 @@
  */
 void ast_channel_callback(ao2_callback_fn *cb_fn);
 
+
+/*! @{ Channel search functions */
+
 /*!
  * \brief Find a channel by name
  *
@@ -1645,7 +1713,7 @@
  * \brief Find a channel by extension and context
  *
  * \arg exten the extension to search for
- * \arg context the context to search for
+ * \arg context the context to search for (optional)
  *
  * Return a channel that is currently at the specified extension and context.
  *
@@ -1653,6 +1721,8 @@
  * \retval NULL if no channel was found
  */
 struct ast_channel *ast_channel_get_by_exten(const char *exten, const char *context);
+
+/*! @} End channel search functions. */
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }