[svn-commits] russell: branch russell/messaging r299245 - /team/russell/messaging/include/a...

[SVN commits to the Digium repositories]

Author: russell
Date: Mon Dec 20 15:33:29 2010
New Revision: 299245

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=299245
Log:
Add docs to the header file

Modified:
    team/russell/messaging/include/asterisk/message.h

Modified: team/russell/messaging/include/asterisk/message.h
URL: http://svnview.digium.com/svn/asterisk/team/russell/messaging/include/asterisk/message.h?view=diff&rev=299245&r1=299244&r2=299245
==============================================================================
--- team/russell/messaging/include/asterisk/message.h (original)
+++ team/russell/messaging/include/asterisk/message.h Mon Dec 20 15:33:29 2010
@@ -22,6 +22,11 @@
  * \brief Out-of-call text message support
  *
  * \author Russell Bryant <russell at digium.com>
+ *
+ * The purpose of this API is to provide support for text messages that
+ * are not session based.  The messages are passed into the Asterisk core
+ * to be routed through the dialplan and potentially sent back out through
+ * a message technology that has been registered through this API.
  */
 
 #ifndef __AST_MESSAGE_H__
@@ -31,8 +36,18 @@
 extern "C" {
 #endif
 
+/*!
+ * \brief A text message.
+ *
+ * This is an opaque type that represents a text message.
+ */
 struct ast_msg;
 
+/*!
+ * \brief A message technology
+ *
+ * A message technology is capable of transmitting text messages.
+ */
 struct ast_msg_tech {
         /*!
          * \brief Name of this message technology
@@ -49,12 +64,47 @@
         int (* const msg_send)(const struct ast_msg *msg, const char *to, const char *from);
 };
 
+/*!
+ * \brief Register a message technology
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 #define ast_msg_tech_register(t) __ast_msg_tech_register((t), ast_module_info->self)
 
+/*!
+ * \brief Register a message technology
+ *
+ * In general, this function should not be used directly.  It should be used through
+ * the ast_msg_tech_register() wrapper.  The only case where this should be used
+ * directly is if something inside of the Asterisk core (as opposed to a loadable
+ * module) was registering a message technology.  In that case, this function would
+ * be used directly and the ast_module argument would be NULL.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int __ast_msg_tech_register(const struct ast_msg_tech *tech, struct ast_module *mod);
 
+/*!
+ * \brief Unregister a message technology.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
 int ast_msg_tech_unregister(const struct ast_msg_tech *tech);
 
+/*!
+ * \brief Allocate a message.
+ *
+ * Allocate a message for the purposes of passing it into the Asterisk core
+ * to be routed through the dialplan.  If ast_msg_queue() is not called, this
+ * message must be destroyed using ast_msg_destroy().  Otherwise, the message
+ * core code will take care of it.
+ *
+ * \return A message object. This function will return NULL if an allocation
+ *         error occurs.
+ */
 struct ast_msg *ast_msg_alloc(void);
 
 /*!
@@ -67,20 +117,46 @@
  */
 struct ast_msg *ast_msg_destroy(struct ast_msg *msg);
 
+/*!
+ * \brief Set the 'to' URI of a message
+ */
 int __attribute__((format(printf, 2, 3)))
-		ast_msg_set_to(struct ast_msg *msg,const char *fmt, ...);
+		ast_msg_set_to(struct ast_msg *msg, const char *fmt, ...);
 
+/*!
+ * \brief Set the 'from' URI of a message
+ */
 int __attribute__((format(printf, 2, 3)))
 		ast_msg_set_from(struct ast_msg *msg, const char *fmt, ...);
 
+/*!
+ * \brief Set the 'body' text of a message (in UTF-8)
+ */
 int __attribute__((format(printf, 2, 3)))
 		ast_msg_set_body(struct ast_msg *msg, const char *fmt, ...);
 
+/*!
+ * \brief Set the dialplan context for this message
+ */
 int __attribute__((format(printf, 2, 3)))
 		ast_msg_set_context(struct ast_msg *msg, const char *fmt, ...);
 
+/*!
+ * \brief Get the body of a message.
+ *
+ * \return The body of the messsage, encoded in UTF-8.
+ */
 const char *ast_msg_get_body(const struct ast_msg *msg);
 
+/*!
+ * \brief Queue a message for routing through the dialplan.
+ *
+ * Regardless of the return value of this function, this funciton will take
+ * care of ensuring that the message object is properly destroyed when needed.
+ *
+ * \retval 0 message successfully queued
+ * \retval non-zero failure, message not sent to dialplan
+ */
 int ast_msg_queue(struct ast_msg *msg);
 
 #if defined(__cplusplus) || defined(c_plusplus)