[asterisk-commits] russell: branch russell/chan_refcount r82560 - /team/russell/chan_refcount/in...

[SVN commits to the Asterisk project]

Author: russell
Date: Mon Sep 17 00:38:58 2007
New Revision: 82560

URL: http://svn.digium.com/view/asterisk?view=rev&rev=82560
Log:
documentation updates

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=82560&r1=82559&r2=82560
==============================================================================
--- team/russell/chan_refcount/include/asterisk/channel.h (original)
+++ team/russell/chan_refcount/include/asterisk/channel.h Mon Sep 17 00:38:58 2007
@@ -635,23 +635,47 @@
 /*! \brief Inherit datastores from a parent to a child. */
 int ast_channel_datastore_inherit(struct ast_channel *from, struct ast_channel *to);
 
-/*! \brief Add a datastore to a channel */
+/*! 
+ * \brief Add a datastore to a channel 
+ *
+ * \note The channel should be locked before calling this function.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int ast_channel_datastore_add(struct ast_channel *chan, struct ast_datastore *datastore);
 
-/*! \brief Remove a datastore from a channel */
+/*! 
+ * \brief Remove a datastore from a channel 
+ *
+ * \note The channel should be locked before calling this function.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int ast_channel_datastore_remove(struct ast_channel *chan, struct ast_datastore *datastore);
 
-/*! \brief Find a datastore on a channel */
+/*! 
+ * \brief Find a datastore on a channel 
+ *
+ * \note The channel should be locked before calling this function.
+ *
+ * \note The datastore returned from this function must not be used if the
+ *       reference to the channel is released.
+ */
 struct ast_datastore *ast_channel_datastore_find(struct ast_channel *chan, const struct ast_datastore_info *info, const char *uid);
 
 /*! \brief Change the state of a channel */
 int ast_setstate(struct ast_channel *chan, enum ast_channel_state);
 
-/*! \brief Create a channel structure 
-    \return Returns NULL on failure to allocate.
-	\note New channels are 
-	by default set to the "default" context and
-	extension "s"
+/*! 
+ * \brief Create a channel structure 
+ *
+ * \retval NULL failure
+ * \retval non-NULL successfully allocated channel
+ *
+ * \note By default, new channels are set to the "s" extension
+ *       and "default" context.
  */
 struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...);
 
@@ -683,30 +707,37 @@
 int ast_queue_control(struct ast_channel *chan, enum ast_control_frame_type control);
 
 /*!
-  \brief Queue a control frame with payload
-  \param chan channel to queue frame onto
-  \param control type of control frame
-  \param data pointer to payload data to be included in frame
-  \param datalen number of bytes of payload data
-  \return zero on success, non-zero on failure
-
-  The supplied payload data is copied into the frame, so the caller's copy
-  is not modified nor freed, and the resulting frame will retain a copy of
-  the data even if the caller frees their local copy.
-
-  \note This method should be treated as a 'network transport'; in other
-  words, your frames may be transferred across an IAX2 channel to another
-  system, which may be a different endianness than yours. Because of this,
-  you should ensure that either your frames will never be expected to work
-  across systems, or that you always put your payload data into 'network byte
-  order' before calling this function.
- 
- \note The channel does not need to be locked before calling this function.
+ * \brief Queue a control frame with payload
+ *
+ * \param chan channel to queue frame onto
+ * \param control type of control frame
+ * \param data pointer to payload data to be included in frame
+ * \param datalen number of bytes of payload data
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ *
+ * The supplied payload data is copied into the frame, so the caller's copy
+ * is not modified nor freed, and the resulting frame will retain a copy of
+ * the data even if the caller frees their local copy.
+ *
+ * \note This method should be treated as a 'network transport'; in other
+ * words, your frames may be transferred across an IAX2 channel to another
+ * system, which may be a different endianness than yours. Because of this,
+ * you should ensure that either your frames will never be expected to work
+ * across systems, or that you always put your payload data into 'network byte
+ * order' before calling this function.
+ *
+ * \note The channel does not need to be locked before calling this function.
  */
 int ast_queue_control_data(struct ast_channel *chan, enum ast_control_frame_type control,
 			   const void *data, size_t datalen);
 
-/*! \brief Change channel name */
+/*! 
+ * \brief Change channel name 
+ *
+ * \note The channel must be locked before calling this function.
+ */
 void ast_change_name(struct ast_channel *chan, char *newname);
 
 /*!
@@ -719,20 +750,26 @@
  */
 struct ast_channel *ast_channel_free(struct ast_channel *);
 
-/*! \brief Requests a channel 
+/*! 
+ * \brief Requests a channel 
+ *
  * \param type type of channel to request
  * \param format requested channel format (codec)
  * \param data data to pass to the channel requester
  * \param status status
+ *
  * Request a channel of a given type, with data as optional information used 
  * by the low level module
- * \return Returns an ast_channel on success, NULL on failure.
+ *
+ * \retval NULL failure
+ * \retval non-NULL channel on success
  */
 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
 
 /*!
  * \brief Request a channel of a given type, with data as optional information used 
- * by the low level module and attempt to place a call on it
+ *        by the low level module and attempt to place a call on it
+ *
  * \param type type of channel to request
  * \param format requested channel format
  * \param data data to pass to the channel requester
@@ -740,6 +777,7 @@
  * \param reason why unsuccessful (if unsuccessful)
  * \param cidnum Caller-ID Number
  * \param cidname Caller-ID Name
+ *
  * \return Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
  * to know if the call was answered or not.
  */