[svn-commits] oej: trunk r48164 - in /trunk: include/asterisk/ main/
svn-commits at lists.digium.com
svn-commits at lists.digium.com
Thu Nov 30 13:34:24 MST 2006
Author: oej
Date: Thu Nov 30 14:34:23 2006
New Revision: 48164
URL: http://svn.digium.com/view/asterisk?view=rev&rev=48164
Log:
Documentation updates
Modified:
trunk/include/asterisk/channel.h
trunk/include/asterisk/devicestate.h
trunk/include/asterisk/pbx.h
trunk/main/devicestate.c
trunk/main/pbx.c
Modified: trunk/include/asterisk/channel.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/channel.h?view=diff&rev=48164&r1=48163&r2=48164
==============================================================================
--- trunk/include/asterisk/channel.h (original)
+++ trunk/include/asterisk/channel.h Thu Nov 30 14:34:23 2006
@@ -143,6 +143,8 @@
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 @@
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 @@
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_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 @@
/*! \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_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 @@
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);
Modified: trunk/include/asterisk/devicestate.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/devicestate.h?view=diff&rev=48164&r1=48163&r2=48164
==============================================================================
--- trunk/include/asterisk/devicestate.h (original)
+++ trunk/include/asterisk/devicestate.h Thu Nov 30 14:34:23 2006
@@ -18,6 +18,8 @@
/*! \file
* \brief Device state management
+ *
+ * \arg See \ref AstExtState
*/
#ifndef _ASTERISK_DEVICESTATE_H
@@ -26,25 +28,18 @@
#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);
Modified: trunk/include/asterisk/pbx.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/pbx.h?view=diff&rev=48164&r1=48163&r2=48164
==============================================================================
--- trunk/include/asterisk/pbx.h (original)
+++ trunk/include/asterisk/pbx.h Thu Nov 30 14:34:23 2006
@@ -43,7 +43,10 @@
#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 @@
* \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 @@
*/
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_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 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_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);
Modified: trunk/main/devicestate.c
URL: http://svn.digium.com/view/asterisk/trunk/main/devicestate.c?view=diff&rev=48164&r1=48163&r2=48164
==============================================================================
--- trunk/main/devicestate.c (original)
+++ trunk/main/devicestate.c Thu Nov 30 14:34:23 2006
@@ -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
@@ -84,9 +84,26 @@
* - 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()
*
*/
Modified: trunk/main/pbx.c
URL: http://svn.digium.com/view/asterisk/trunk/main/pbx.c?view=diff&rev=48164&r1=48163&r2=48164
==============================================================================
--- trunk/main/pbx.c (original)
+++ trunk/main/pbx.c Thu Nov 30 14:34:23 2006
@@ -193,7 +193,9 @@
/*! \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 */
More information about the svn-commits
mailing list