From 5a2011b9d74f97c2355fe6c99f72a3617adc17a3 Mon Sep 17 00:00:00 2001 From: oej Date: Fri, 24 Nov 2006 14:00:19 +0000 Subject: 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. git-svn-id: http://svn.digium.com/svn/asterisk/trunk@47986 f38db490-d61c-443f-a65b-d21fe96a405b --- include/asterisk/causes.h | 62 ++++++++++++++++++++++++++++++++++++++++++++ include/asterisk/channel.h | 35 +++++++++++++------------ include/asterisk/doxyref.h | 64 +++++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 142 insertions(+), 19 deletions(-) (limited to 'include/asterisk') diff --git a/include/asterisk/causes.h b/include/asterisk/causes.h index fc27c7970..ad3fa672d 100644 --- a/include/asterisk/causes.h +++ b/include/asterisk/causes.h @@ -23,6 +23,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 #define AST_CAUSE_NO_ROUTE_TRANSIT_NET 2 diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 94b46a916..6521e9762 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -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 @@ 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 */ diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 49e282816..9211b1233 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -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 -- cgit v1.2.3