From 446a06679aa0a1b96bb09d6e16514a12124686af Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Thu, 30 Nov 2006 20:34:23 +0000 Subject: Documentation updates git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48164 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/channel.h | 32 +++++++++++++++++++++++--------- include/asterisk/devicestate.h | 33 ++++++++++++++------------------- include/asterisk/pbx.h | 39 ++++++++++++++++++++++++++++++++++----- main/devicestate.c | 19 ++++++++++++++++++- main/pbx.c | 4 +++- 5 files changed, 92 insertions(+), 35 deletions(-) diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 6521e9762..ff0901fb2 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -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); diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h index 97d24c16f..85a1235c9 100644 --- a/include/asterisk/devicestate.h +++ b/include/asterisk/devicestate.h @@ -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); diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index fbaef5477..17e7b1416 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -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); diff --git a/main/devicestate.c b/main/devicestate.c index 2fd8d82bd..4a881afef 100644 --- a/main/devicestate.c +++ b/main/devicestate.c @@ -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() * */ diff --git a/main/pbx.c b/main/pbx.c index 60a89e104..370087412 100644 --- a/main/pbx.c +++ b/main/pbx.c @@ -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 */ -- cgit v1.2.3