Documentation updates
authorOlle Johansson <oej@edvina.net>
Thu, 30 Nov 2006 20:34:23 +0000 (20:34 +0000)
committerOlle Johansson <oej@edvina.net>
Thu, 30 Nov 2006 20:34:23 +0000 (20:34 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48164 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/channel.h
include/asterisk/devicestate.h
include/asterisk/pbx.h
main/devicestate.c
main/pbx.c

index 6521e97..ff0901f 100644 (file)
@@ -143,6 +143,8 @@ enum ast_bridge_result {
 
 typedef unsigned long long ast_group_t;
 
+/*! \todo Add an explanation of an Asterisk generator 
+*/
 struct ast_generator {
        void *(*alloc)(struct ast_channel *chan, void *params);
        void (*release)(struct ast_channel *chan, void *data);
@@ -274,8 +276,8 @@ struct ast_channel_tech {
        int (* func_channel_write)(struct ast_channel *chan, char *function, char *data, const char *value);
 };
 
-struct ast_channel_spy_list;
-struct ast_channel_whisper_buffer;
+struct ast_channel_spy_list;   /*!< \todo Add explanation here */
+struct ast_channel_whisper_buffer;     /*!< \todo Add explanation here */
 
 #define        DEBUGCHAN_FLAG  0x80000000
 #define        FRAMECOUNT_INC(x)       ( ((x) & DEBUGCHAN_FLAG) | ((x++) & ~DEBUGCHAN_FLAG) )
@@ -492,6 +494,7 @@ enum {
        AST_FEATURE_PARKCALL =     (1 << 5),
 };
 
+/*! \brief bridge configuration */
 struct ast_bridge_config {
        struct ast_flags features_caller;
        struct ast_flags features_callee;
@@ -750,7 +753,7 @@ int ast_call(struct ast_channel *chan, char *addr, int timeout);
 int ast_indicate(struct ast_channel *chan, int condition);
 
 /*! \brief Indicates condition of channel, with payload
- * \note Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
+ * \note Indicate a condition such as AST_CONTROL_HOLD with payload being music on hold class
  * \param chan channel to change the indication
  * \param condition which condition to indicate on the channel
  * \param data pointer to payload data
@@ -817,14 +820,12 @@ int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
 
 /*! \brief Reads a frame
  * \param chan channel to read a frame from
-       Read a frame.  
-       \return Returns a frame, or NULL on error.  If it returns NULL, you
-               best just stop reading frames and assume the channel has been
-               disconnected. */
+ * \return Returns a frame, or NULL on error.  If it returns NULL, you
+       best just stop reading frames and assume the channel has been
+       disconnected. */
 struct ast_frame *ast_read(struct ast_channel *chan);
 
 /*! \brief Reads a frame, returning AST_FRAME_NULL frame if audio. 
- * Read a frame. 
        \param chan channel to read a frame from
        \return  Returns a frame, or NULL on error.  If it returns NULL, you
                best just stop reading frames and assume the channel has been
@@ -892,7 +893,20 @@ int ast_recvchar(struct ast_channel *chan, int timeout);
  */
 int ast_senddigit(struct ast_channel *chan, char digit);
 
+/*! \brief Send a DTMF digit to a channel
+ * Send a DTMF digit to a channel.
+ * \param chan channel to act upon
+ * \param digit the DTMF digit to send, encoded in ASCII
+ * \return Returns 0 on success, -1 on failure
+ */
 int ast_senddigit_begin(struct ast_channel *chan, char digit);
+/*! \brief Send a DTMF digit to a channel
+
+ * Send a DTMF digit to a channel.
+ * \param chan channel to act upon
+ * \param digit the DTMF digit to send, encoded in ASCII
+ * \return Returns 0 on success, -1 on failure
+ */
 int ast_senddigit_end(struct ast_channel *chan, char digit);
 
 /*! \brief Receives a text string from a channel
@@ -1350,7 +1364,7 @@ struct ast_variable *ast_channeltype_list(void);
   audio samples, and then to mix in audio from the whisper buffer if it
   is available.
 
-  Note: This function performs no locking; you must hold the channel's lock before
+  \note Note: This function performs no locking; you must hold the channel's lock before
   calling this function.
  */
 int ast_channel_whisper_start(struct ast_channel *chan);
index 97d24c1..85a1235 100644 (file)
@@ -18,6 +18,8 @@
 
 /*! \file
  * \brief Device state management
+ *
+ * \arg See \ref AstExtState
  */
 
 #ifndef _ASTERISK_DEVICESTATE_H
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
 #endif
-
-/*! Device is valid but channel didn't know state */
-#define AST_DEVICE_UNKNOWN     0
-/*! Device is not used */
-#define AST_DEVICE_NOT_INUSE   1
-/*! Device is in use */
-#define AST_DEVICE_INUSE       2
-/*! Device is busy */
-#define AST_DEVICE_BUSY                3
-/*! Device is invalid */
-#define AST_DEVICE_INVALID     4
-/*! Device is unavailable */
-#define AST_DEVICE_UNAVAILABLE 5
-/*! Device is ringing */
-#define AST_DEVICE_RINGING     6
-/*! Device is ringing *and* in use */
-#define AST_DEVICE_RINGINUSE   7
-/*! Device is on hold */
-#define AST_DEVICE_ONHOLD      8
+/*! @name DeviceStates */
+/*! \@{ */
+#define AST_DEVICE_UNKNOWN     0 /*!< Device is valid but channel didn't know state */
+#define AST_DEVICE_NOT_INUSE   1 /*!< Device is not used */
+#define AST_DEVICE_INUSE       2 /*!< Device is in use */
+#define AST_DEVICE_BUSY                3 /*!< Device is busy */
+#define AST_DEVICE_INVALID     4 /*!< Device is invalid */
+#define AST_DEVICE_UNAVAILABLE 5 /*!< Device is unavailable */
+#define AST_DEVICE_RINGING     6 /*!< Device is ringing */
+#define AST_DEVICE_RINGINUSE   7 /*!< Device is ringing *and* in use */
+#define AST_DEVICE_ONHOLD      8 /*!< Device is on hold */
+/*! \@} */
 
 /*! \brief Devicestate watcher call back */
 typedef int (*ast_devstate_cb_type)(const char *dev, int state, void *data);
index fbaef54..17e7b14 100644 (file)
@@ -43,7 +43,10 @@ extern "C" {
 
 #define PRIORITY_HINT  -1      /*!< Special Priority for a hint */
 
-/*! \brief Extension states */
+/*! \brief Extension states 
+       \note States can be combined 
+       - \ref AstExtState
+*/
 enum ast_extension_states {
        AST_EXTENSION_REMOVED = -2,     /*!< Extension removed */
        AST_EXTENSION_DEACTIVATED = -1, /*!< Extension hint removed */
@@ -174,6 +177,20 @@ int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data);
  * \return NULL on failure, and an ast_context structure on success
  */
 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
+
+/*!
+ * \brief Register a new context or find an existing one
+ *
+ * \param extcontexts pointer to the ast_context structure pointer
+ * \param name name of the new context
+ * \param registrar registrar of the context
+ *
+ * This will first search for a context with your name.  If it exists already, it will not
+ * create a new one.  If it does not exist, it will create a new one with the given name
+ * and registrar.
+ *
+ * \return NULL on failure, and an ast_context structure on success
+ */
 struct ast_context *ast_context_find_or_create(struct ast_context **extcontexts, const char *name, const char *registrar);
 
 /*!
@@ -211,6 +228,11 @@ void ast_context_destroy(struct ast_context *con, const char *registrar);
  */
 struct ast_context *ast_context_find(const char *name);
 
+/*! \brief The result codes when starting the PBX on a channel
+       with \ref ast_pbx_start()
+
+       AST_PBX_CALL_LIMIT refers to the maxcalls call limit in asterisk.conf
+ */
 enum ast_pbx_result {
        AST_PBX_SUCCESS = 0,
        AST_PBX_FAILED = -1,
@@ -356,7 +378,7 @@ int ast_extension_state_add(const char *context, const char *exten,
 int ast_extension_state_del(int id, ast_state_cb_type callback);
 
 /*! 
- * \brief If an extension exists, return non-zero
+ * \brief If an extension hint exists, return non-zero
  * 
  * \param hint buffer for hint
  * \param maxlen size of hint buffer
@@ -728,7 +750,9 @@ int ast_pbx_outgoing_app(const char *type, int format, void *data, int timeout,
  */
 int pbx_checkcondition(const char *condition);
 
-/* Functions for returning values from structures */
+/*! @name 
+ * Functions for returning values from structures */
+/*! @{ */
 const char *ast_get_context_name(struct ast_context *con);
 const char *ast_get_extension_name(struct ast_exten *exten);
 struct ast_context *ast_get_extension_context(struct ast_exten *exten);
@@ -736,21 +760,26 @@ const char *ast_get_include_name(struct ast_include *include);
 const char *ast_get_ignorepat_name(struct ast_ignorepat *ip);
 const char *ast_get_switch_name(struct ast_sw *sw);
 const char *ast_get_switch_data(struct ast_sw *sw);
+/*! @} */
 
-/* Other extension stuff */
+/*! @name Other Extension stuff */
+/*! @{ */
 int ast_get_extension_priority(struct ast_exten *exten);
 int ast_get_extension_matchcid(struct ast_exten *e);
 const char *ast_get_extension_cidmatch(struct ast_exten *e);
 const char *ast_get_extension_app(struct ast_exten *e);
 const char *ast_get_extension_label(struct ast_exten *e);
 void *ast_get_extension_app_data(struct ast_exten *e);
+/*! @} */
 
-/* Registrar info functions ... */
+/*! @name Registrar info functions ... */
+/*! @{ */
 const char *ast_get_context_registrar(struct ast_context *c);
 const char *ast_get_extension_registrar(struct ast_exten *e);
 const char *ast_get_include_registrar(struct ast_include *i);
 const char *ast_get_ignorepat_registrar(struct ast_ignorepat *ip);
 const char *ast_get_switch_registrar(struct ast_sw *sw);
+/*! @} */
 
 /* Walking functions ... */
 struct ast_context *ast_walk_contexts(struct ast_context *con);
index 2fd8d82..4a881af 100644 (file)
@@ -67,7 +67,7 @@
  *     system. res_jabber.c can subscribe and watch such states
  *     in jabber/xmpp based systems.
  *
- *     \section AstExtStateARch Architecture
+ *     \section AstDevStateArch Architecture for devicestates
  *
  *     When a channel driver or asterisk app changes state for 
  *     a watched object, it alerts the core. The core queues
  *     - Device states
  *             \arg \ref devicestate.c 
  *             \arg \ref devicestate.h 
+ *
+ *     \section AstExtStateArch Architecture for extension states
+ *     
+ *     Hints are connected to extension. If an extension changes state
+ *     it checks the hint devices. If there is a hint, the callbacks into
+ *     device states are checked. The aggregated state is set for the hint
+ *     and reported back.
+ *
  *     - Extension states
+ *             \arg \ref enum ast_extension_states
  *             \arg \ref pbx.c 
  *             \arg \ref pbx.h 
+ *     - Structures
+ *             - \ref struct ast_state_cb  Callbacks for watchers
+ *             - Callback ast_state_cb_type
+ *             - \ref struct ast_hint
+ *     - Functions
+ *             - ast_extension_state_add()
+ *             - ast_extension_state_del()
+ *             - ast_get_hint()
  *     
  */
 
index 60a89e1..3700874 100644 (file)
@@ -193,7 +193,9 @@ struct ast_state_cb {
 /*! \brief Structure for dial plan hints
 
   \note Hints are pointers from an extension in the dialplan to one or
-  more devices (tech/name) */
+  more devices (tech/name) 
+       - See \ref AstExtState
+*/
 struct ast_hint {
        struct ast_exten *exten;        /*!< Extension */
        int laststate;                  /*!< Last known state */