[svn-commits] oej: trunk r47986 - in /trunk: include/asterisk/ main/
svn-commits at lists.digium.com
svn-commits at lists.digium.com
Fri Nov 24 07:00:20 MST 2006
Author: oej
Date: Fri Nov 24 08:00:19 2006
New Revision: 47986
URL: http://svn.digium.com/view/asterisk?view=rev&rev=47986
Log:
Doxygen update
- Document cause codes
- Document a bit more on channel variables - global, predefined and local
- Fix some doxygen in channel.h. Adding one comment for two definitions does not
work. They won't be copied to each.
Modified:
trunk/include/asterisk/causes.h
trunk/include/asterisk/channel.h
trunk/include/asterisk/doxyref.h
trunk/main/pbx.c
Modified: trunk/include/asterisk/causes.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/causes.h?view=diff&rev=47986&r1=47985&r2=47986
==============================================================================
--- trunk/include/asterisk/causes.h (original)
+++ trunk/include/asterisk/causes.h Fri Nov 24 08:00:19 2006
@@ -22,6 +22,68 @@
#ifndef _ASTERISK_CAUSES_H
#define _ASTERISK_CAUSES_H
+
+/*! \page AstCauses Hangup Causes for Asterisk
+
+The Asterisk hangup causes are delivered to the dialplan in the
+${HANGUPCAUSE} channel variable after a call (after execution
+of "dial").
+
+In SIP, we have a conversion table to convert between SIP
+return codes and Q.931 both ways. This is to improve SIP/ISDN
+compatibility.
+
+These are the current codes, based on the Q.931
+specification:
+
+ - AST_CAUSE_UNALLOCATED 1
+ - AST_CAUSE_NO_ROUTE_TRANSIT_NET 2
+ - AST_CAUSE_NO_ROUTE_DESTINATION 3
+ - AST_CAUSE_CHANNEL_UNACCEPTABLE 6
+ - AST_CAUSE_CALL_AWARDED_DELIVERED 7
+ - AST_CAUSE_NORMAL_CLEARING 16
+ - AST_CAUSE_USER_BUSY 17
+ - AST_CAUSE_NO_USER_RESPONSE 18
+ - AST_CAUSE_NO_ANSWER 19
+ - AST_CAUSE_CALL_REJECTED 21
+ - AST_CAUSE_NUMBER_CHANGED 22
+ - AST_CAUSE_DESTINATION_OUT_OF_ORDER 27
+ - AST_CAUSE_INVALID_NUMBER_FORMAT 28
+ - AST_CAUSE_FACILITY_REJECTED 29
+ - AST_CAUSE_RESPONSE_TO_STATUS_ENQUIRY 30
+ - AST_CAUSE_NORMAL_UNSPECIFIED 31
+ - AST_CAUSE_NORMAL_CIRCUIT_CONGESTION 34
+ - AST_CAUSE_NETWORK_OUT_OF_ORDER 38
+ - AST_CAUSE_NORMAL_TEMPORARY_FAILURE 41
+ - AST_CAUSE_SWITCH_CONGESTION 42
+ - AST_CAUSE_ACCESS_INFO_DISCARDED 43
+ - AST_CAUSE_REQUESTED_CHAN_UNAVAIL 44
+ - AST_CAUSE_PRE_EMPTED 45
+ - AST_CAUSE_FACILITY_NOT_SUBSCRIBED 50
+ - AST_CAUSE_OUTGOING_CALL_BARRED 52
+ - AST_CAUSE_INCOMING_CALL_BARRED 54
+ - AST_CAUSE_BEARERCAPABILITY_NOTAUTH 57
+ - AST_CAUSE_BEARERCAPABILITY_NOTAVAIL 58
+ - AST_CAUSE_BEARERCAPABILITY_NOTIMPL 65
+ - AST_CAUSE_CHAN_NOT_IMPLEMENTED 66
+ - AST_CAUSE_FACILITY_NOT_IMPLEMENTED 69
+ - AST_CAUSE_INVALID_CALL_REFERENCE 81
+ - AST_CAUSE_INCOMPATIBLE_DESTINATION 88
+ - AST_CAUSE_INVALID_MSG_UNSPECIFIED 95
+ - AST_CAUSE_MANDATORY_IE_MISSING 96
+ - AST_CAUSE_MESSAGE_TYPE_NONEXIST 97
+ - AST_CAUSE_WRONG_MESSAGE 98
+ - AST_CAUSE_IE_NONEXIST 99
+ - AST_CAUSE_INVALID_IE_CONTENTS 100
+ - AST_CAUSE_WRONG_CALL_STATE 101
+ - AST_CAUSE_RECOVERY_ON_TIMER_EXPIRE 102
+ - AST_CAUSE_MANDATORY_IE_LENGTH_ERROR 103
+ - AST_CAUSE_PROTOCOL_ERROR 111
+ - AST_CAUSE_INTERWORKING 127
+
+For more information:
+- \ref app_dial.c
+*/
/* Causes for disconnection (from Q.931) */
#define AST_CAUSE_UNALLOCATED 1
Modified: trunk/include/asterisk/channel.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/channel.h?view=diff&rev=47986&r1=47985&r2=47986
==============================================================================
--- trunk/include/asterisk/channel.h (original)
+++ trunk/include/asterisk/channel.h Fri Nov 24 08:00:19 2006
@@ -84,6 +84,11 @@
*/
+/*! \page AstFileDesc File descriptors
+ Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
+ in the \ref ast_channel structure.
+*/
+
#ifndef _ASTERISK_CHANNEL_H
#define _ASTERISK_CHANNEL_H
@@ -336,8 +341,8 @@
AST_STRING_FIELD(uniqueid); /*!< Unique Channel Identifier */
);
- /*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. */
- int fds[AST_MAX_FDS];
+ /*! \brief File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1. See \ref AstFileDesc */
+ int fds[AST_MAX_FDS];
void *music_state; /*!< Music State*/
void *generatordata; /*!< Current generator data if there is any */
@@ -351,12 +356,11 @@
struct ast_channel *masqr; /*!< Who we are masquerading as */
int cdrflags; /*!< Call Detail Record Flags */
- /*! \brief Whether or not we have been hung up... Do not set this value
- directly, use ast_softhangup */
- int _softhangup;
+ int _softhangup; /*!< Whether or not we have been hung up... Do not set this value
+ directly, use ast_softhangup() */
time_t whentohangup; /*!< Non-zero, set to actual time when channel is to be hung up */
pthread_t blocker; /*!< If anyone is blocking, this is them */
- ast_mutex_t lock; /*!< Lock, can be used to lock a channel for some operations */
+ ast_mutex_t lock; /*!< Lock, can be used to lock a channel for some operations - see ast_channel_lock() */
const char *blockproc; /*!< Procedure causing blocking */
const char *appl; /*!< Current application */
@@ -373,7 +377,7 @@
int (*timingfunc)(void *data);
void *timingdata;
- enum ast_channel_state _state; /*!< State of line -- Don't write directly, use ast_setstate */
+ enum ast_channel_state _state; /*!< State of line -- Don't write directly, use ast_setstate() */
int rings; /*!< Number of rings so far */
struct ast_callerid cid; /*!< Caller ID, name, presentation etc */
char dtmfq[AST_MAX_EXTENSION]; /*!< Any/all queued DTMF characters */
@@ -397,17 +401,16 @@
struct ast_channel_monitor *monitor; /*!< Channel monitoring */
- /*! Track the read/written samples for monitor use */
- unsigned long insmpl;
- unsigned long outsmpl;
-
- /* Frames in/out counters. The high bit is a debug mask, so
- * the counter is only in the remaining bits
- */
- unsigned int fin;
- unsigned int fout;
+ unsigned long insmpl; /*!< Track the read/written samples for monitor use */
+ unsigned long outsmpl; /*!< Track the read/written samples for monitor use */
+
+ unsigned int fin; /*!< Frames in counters. The high bit is a debug mask, so
+ * the counter is only in the remaining bits */
+ unsigned int fout; /*!< Frames out counters. The high bit is a debug mask, so
+ * the counter is only in the remaining bits */
int hangupcause; /*!< Why is the channel hanged up. See causes.h */
- struct varshead varshead; /*!< A linked list for channel variables */
+ struct varshead varshead; /*!< A linked list for channel variables
+ (see \ref AstChanVar ) */
ast_group_t callgroup; /*!< Call group for call pickups */
ast_group_t pickupgroup; /*!< Pickup group - which calls groups can be picked up? */
unsigned int flags; /*!< channel flags of AST_FLAG_ type */
Modified: trunk/include/asterisk/doxyref.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/doxyref.h?view=diff&rev=47986&r1=47985&r2=47986
==============================================================================
--- trunk/include/asterisk/doxyref.h (original)
+++ trunk/include/asterisk/doxyref.h Fri Nov 24 08:00:19 2006
@@ -135,9 +135,67 @@
* \verbinclude video.txt
*/
-/*! \page AstVar Global channel variables
- * \section globchan Global Channel Variables
+/*! \page AstVar Globally predefined channel variables
+ * \section globchan Globally predefined channel variables
+ *
+ * More and more of these variables are being replaced by dialplan functions.
+ * Some still exist though and some that does still exist needs to move to
+ * dialplan functions.
+ *
+ * See also
+ * - \ref pbx_retrieve_variable()
+ * - \ref AstChanVar
+ *
* \verbinclude channelvariables.txt
+
+ */
+
+/*! \page AstChanVar Asterisk Dialplan Variables
+ * Asterisk Dialplan variables are divided into three groups:
+ * - Predefined global variables, handled by the PBX core
+ * - Global variables, that exist for the duration of the pbx execution
+ * - Channel variables, that exist during a channel
+ *
+ * Global variables are reachable in all channels, all of the time.
+ * Channel variables are only reachable within the channel.
+ *
+ * For more information on the predefined variables, see \ref AstVar
+ *
+ * Global and Channel variables:
+ * - Names are Case insensitive
+ * - Names that start with a character, but are alphanumeric
+ * - Global variables are defined and reached with the GLOBAL() dialplan function
+ * and the set application, like
+ *
+ * exten => 1234,1,set(GLOBAL(myvariable)=tomteluva)
+ *
+ * - \ref func_global.c
+ *
+ * - Channel variables are defined with the set() dialplan application
+ *
+ * exten => 1234,1,set(xmasattribute=tomtegröt)
+ *
+ * - Some channels also supports setting channel variables with the \b setvar=
+ * configuraiton option for a device or line.
+ *
+ * \section AstChanVar_globalvars Global Variables
+ * Global variables can also be set in the [globals] section of extensions.conf. The
+ * setting \b clearglobalvars in extensions.conf [general] section affects whether
+ * or not the global variables defined in \b globals are reset at dialplan reload.
+ *
+ * There are CLI commands to change and read global variables. This can be handy
+ * to reset counters at midnight from an external script.
+ *
+ * \section AstChanVar_devnotes Developer notes
+ * Variable handling is managed within \ref pbx.c
+ * You need to include pbx.h to reach these functions.
+ * - \ref pbx_builtin_setvar_helper()
+ * - \ref pbx_builtin_getvar_helper()
+ *
+ * The variables is a linked list stored in the channel data structure
+ * with the list starting at varshead in struct ast_channel
+ *
+ *
*/
/*! \page AstENUM ENUM
@@ -209,7 +267,7 @@
* \verbinclude features.conf.sample
*/
-/*! \page Config_followme followme.conf
+/*! \page Config_followme Followme: An application for simple follow-me calls
* \section followmeconf Followme.conf
* - See app_followme.c
* \verbinclude followme.conf.sample
Modified: trunk/main/pbx.c
URL: http://svn.digium.com/view/asterisk/trunk/main/pbx.c?view=diff&rev=47986&r1=47985&r2=47986
==============================================================================
--- trunk/main/pbx.c (original)
+++ trunk/main/pbx.c Fri Nov 24 08:00:19 2006
@@ -1094,9 +1094,12 @@
return ret;
}
-/*! \brief pbx_retrieve_variable: Support for Asterisk built-in variables and
- functions in the dialplan
- ---*/
+/*! \brief Support for Asterisk built-in variables and functions in the dialplan
+
+\note See also
+ - \ref AstVar Channel variables
+ - \ref AstCauses The HANGUPCAUSE variable
+ */
void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp)
{
const char not_found = '\0';
More information about the svn-commits
mailing list