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;
 
 
 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);
 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);
 };
 
        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) )
 
 #define        DEBUGCHAN_FLAG  0x80000000
 #define        FRAMECOUNT_INC(x)       ( ((x) & DEBUGCHAN_FLAG) | ((x++) & ~DEBUGCHAN_FLAG) )
@@ -492,6 +494,7 @@ enum {
        AST_FEATURE_PARKCALL =     (1 << 5),
 };
 
        AST_FEATURE_PARKCALL =     (1 << 5),
 };
 
+/*! \brief bridge configuration */
 struct ast_bridge_config {
        struct ast_flags features_caller;
        struct ast_flags features_callee;
 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
 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
  * \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
 
 /*! \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. 
 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
        \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);
 
  */
 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);
 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
 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.
 
   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);
   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
 
 /*! \file
  * \brief Device state management
+ *
+ * \arg See \ref AstExtState
  */
 
 #ifndef _ASTERISK_DEVICESTATE_H
  */
 
 #ifndef _ASTERISK_DEVICESTATE_H
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
 #endif
 #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);
 
 /*! \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 */
 
 
 #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 */
 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);
  * \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);
 
 /*!
 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);
 
  */
 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,
 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);
 
 /*! 
 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
  * 
  * \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);
 
  */
 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);
 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);
 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);
 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);
 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);
 
 /* 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.
  *
  *     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
  *
  *     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 
  *     - 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
  *     - Extension states
+ *             \arg \ref enum ast_extension_states
  *             \arg \ref pbx.c 
  *             \arg \ref pbx.h 
  *             \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
 /*! \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 */
 struct ast_hint {
        struct ast_exten *exten;        /*!< Extension */
        int laststate;                  /*!< Last known state */