Doxygen update
authorOlle Johansson <oej@edvina.net>
Fri, 24 Nov 2006 14:00:19 +0000 (14:00 +0000)
committerOlle Johansson <oej@edvina.net>
Fri, 24 Nov 2006 14:00:19 +0000 (14:00 +0000)
- 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.

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@47986 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/causes.h
include/asterisk/channel.h
include/asterisk/doxyref.h
main/pbx.c

index fc27c79..ad3fa67 100644 (file)
 #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
 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET                 2
index 94b46a9..6521e97 100644 (file)
 
 */
 
+/*! \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 @@ struct ast_channel {
                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 {
        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 @@ struct ast_channel {
        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 {
 
        struct ast_channel_monitor *monitor;            /*!< Channel monitoring */
 
-       /*! Track the read/written samples for monitor use */
-       unsigned long insmpl;
-       unsigned long outsmpl;
+       unsigned long insmpl;                           /*!< Track the read/written samples for monitor use */
+       unsigned long outsmpl;                          /*!< Track the read/written samples for monitor use */
 
-       /* 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 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 */
index 49e2828..9211b12 100644 (file)
@@ -135,9 +135,67 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  \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 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  * \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
index f79461e..60a89e1 100644 (file)
@@ -1094,9 +1094,12 @@ static char *substring(const char *value, int offset, int length, char *workspac
        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';