From c474809cdf5ab65dd1af0e8840b656f75656dce7 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Thu, 15 Mar 2007 22:25:12 +0000 Subject: [PATCH] Merge changes from svn/asterisk/team/russell/LaTeX_docs. * Convert most of the doc directory into a single LaTeX formatted document so that we can generate a PDF, HTML, or other formats from this information. * Add a CLI command to dump the application documentation into LaTeX format which will only be include if the configure script is run with --enable-dev-mode. * The PDF turned out to be close to 1 MB, so it is not included. However, you can simply run "make asterisk.pdf" to generate it yourself. We may include it in release tarballs or have automatically generated ones on the web site, but that has yet to be decided. git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/1.4@58931 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- Makefile | 18 + apps/app_voicemail.c | 14 +- build_tools/make_buildopts_h | 6 +- configure | 51 +- configure.ac | 1 + doc/00README.1st | 74 - doc/PEERING | 4 + doc/{ael.txt => ael.tex} | 478 ++- doc/{ajam.txt => ajam.tex} | 38 +- doc/{app-sms.txt => app-sms.tex} | 93 +- doc/apps.txt | 10 - doc/ast_appdocs.tex | 3225 +++++++++++++++++ doc/asterisk-conf.tex | 130 + doc/asterisk-conf.txt | 83 - doc/asterisk.tex | 132 + doc/billing.tex | 87 + doc/billing.txt | 105 - doc/callingpres.txt | 18 - doc/cdrdriver.tex | 431 +++ doc/cdrdriver.txt | 215 -- doc/chaniax.tex | 84 + doc/chaniax.txt | 369 -- doc/channels.txt | 44 - ...nnelvariables.txt => channelvariables.tex} | 364 +- doc/{cliprompt.txt => cliprompt.tex} | 19 +- doc/{configuration.txt => configuration.tex} | 72 +- doc/cygwin.txt | 9 - doc/{dundi.txt => dundi.tex} | 4 - doc/{enum.txt => enum.tex} | 143 +- doc/extconfig.txt | 91 - doc/{extensions.txt => extensions.tex} | 48 +- doc/{freetds.txt => freetds.tex} | 8 +- doc/h323.txt | 22 - doc/hardware.tex | 100 + doc/hardware.txt | 74 - doc/iax.txt | 67 - doc/{ices.txt => ices.tex} | 9 +- doc/{imapstorage.txt => imapstorage.tex} | 114 +- doc/{ip-tos.txt => ip-tos.tex} | 34 +- doc/{jitterbuffer.txt => jitterbuffer.tex} | 99 +- doc/linkedlists.txt | 98 - doc/{localchannel.txt => localchannel.tex} | 30 +- doc/{manager.txt => manager.tex} | 107 +- doc/math.txt | 69 - doc/{misdn.txt => misdn.tex} | 189 +- doc/model.txt | 15 - doc/{mp3.txt => mp3.tex} | 4 +- doc/musiconhold-fpm.txt | 8 - doc/mysql.txt | 15 - doc/{odbcstorage.txt => odbcstorage.tex} | 9 +- doc/{privacy.txt => privacy.tex} | 82 +- doc/{queuelog.txt => queuelog.tex} | 7 +- ...s.txt => queues-with-callback-members.tex} | 91 +- doc/radius.txt | 203 -- doc/{realtime.txt => realtime.tex} | 74 +- doc/{security.txt => security.tex} | 13 +- doc/sla.pdf | Bin 68499 -> 0 bytes doc/sla.tex | 16 +- main/pbx.c | 56 + makeopts.in | 1 + 60 files changed, 5330 insertions(+), 2744 deletions(-) delete mode 100644 doc/00README.1st rename doc/{ael.txt => ael.tex} (79%) rename doc/{ajam.txt => ajam.tex} (73%) rename doc/{app-sms.txt => app-sms.tex} (95%) delete mode 100644 doc/apps.txt create mode 100644 doc/ast_appdocs.tex create mode 100644 doc/asterisk-conf.tex delete mode 100644 doc/asterisk-conf.txt create mode 100644 doc/asterisk.tex create mode 100644 doc/billing.tex delete mode 100644 doc/billing.txt delete mode 100644 doc/callingpres.txt create mode 100644 doc/cdrdriver.tex delete mode 100644 doc/cdrdriver.txt create mode 100644 doc/chaniax.tex delete mode 100644 doc/chaniax.txt delete mode 100644 doc/channels.txt rename doc/{channelvariables.txt => channelvariables.tex} (78%) rename doc/{cliprompt.txt => cliprompt.tex} (70%) rename doc/{configuration.txt => configuration.tex} (76%) delete mode 100644 doc/cygwin.txt rename doc/{dundi.txt => dundi.tex} (87%) rename doc/{enum.txt => enum.tex} (79%) delete mode 100644 doc/extconfig.txt rename doc/{extensions.txt => extensions.tex} (63%) rename doc/{freetds.txt => freetds.tex} (63%) delete mode 100644 doc/h323.txt create mode 100644 doc/hardware.tex delete mode 100644 doc/hardware.txt delete mode 100644 doc/iax.txt rename doc/{ices.txt => ices.tex} (70%) rename doc/{imapstorage.txt => imapstorage.tex} (72%) rename doc/{ip-tos.txt => ip-tos.tex} (81%) rename doc/{jitterbuffer.txt => jitterbuffer.tex} (57%) delete mode 100644 doc/linkedlists.txt rename doc/{localchannel.txt => localchannel.tex} (69%) rename doc/{manager.txt => manager.tex} (79%) delete mode 100644 doc/math.txt rename doc/{misdn.txt => misdn.tex} (64%) delete mode 100644 doc/model.txt rename doc/{mp3.txt => mp3.tex} (87%) delete mode 100644 doc/musiconhold-fpm.txt delete mode 100644 doc/mysql.txt rename doc/{odbcstorage.txt => odbcstorage.tex} (89%) rename doc/{privacy.txt => privacy.tex} (90%) rename doc/{queuelog.txt => queuelog.tex} (95%) rename doc/{queues-with-callback-members.txt => queues-with-callback-members.tex} (90%) delete mode 100644 doc/radius.txt rename doc/{realtime.txt => realtime.tex} (71%) rename doc/{security.txt => security.tex} (93%) delete mode 100644 doc/sla.pdf diff --git a/Makefile b/Makefile index 0c460428d3..609ca06cab 100644 --- a/Makefile +++ b/Makefile @@ -46,6 +46,7 @@ export AGI_DIR export ASTCONFPATH export NOISY_BUILD export MENUSELECT_CFLAGS +export AST_DEVMODE export CC export CXX export AR @@ -676,4 +677,21 @@ menuselect-tree: $(foreach dir,$(filter-out main,$(MOD_SUBDIRS)),$(wildcard $(di @echo "Generating input for menuselect ..." @build_tools/prep_moduledeps > $@ +asterisk.pdf: doc/asterisk.pdf + +doc/asterisk.pdf: +ifeq ($(findstring rubber,$(RUBBER)),) + @echo "**********************************************" + @echo "** You must install the \"rubber\" tool ***" + @echo "** to generate the Asterisk reference PDF. ***" + @echo "**********************************************" +else + @echo "**********************************************" + @echo "** The Asterisk reference PDF will now be ***" + @echo "** generated. When complete, it will be ***" + @echo "** located at doc/asterisk.pdf. ***" + @echo "**********************************************" + @cd doc && rubber asterisk.tex +endif + .PHONY: menuselect main sounds clean dist-clean distclean all prereqs cleantest uninstall _uninstall uninstall-all dont-optimize $(SUBDIRS_INSTALL) $(SUBDIRS_CLEAN) $(SUBDIRS_UNINSTALL) $(SUBDIRS) $(MOD_SUBDIRS_EMBED_LDSCRIPT) $(MOD_SUBDIRS_EMBED_LDFLAGS) $(MOD_SUBDIRS_EMBED_LIBS) diff --git a/apps/app_voicemail.c b/apps/app_voicemail.c index c374679001..184ef125fa 100644 --- a/apps/app_voicemail.c +++ b/apps/app_voicemail.c @@ -1905,7 +1905,7 @@ static void make_email_file(FILE *p, char *srcemail, struct ast_vm_user *vmu, in fprintf(p, "Subject: New message %d in mailbox %s" ENDL, msgnum + 1, mailbox); else fprintf(p, "Subject: [PBX]: New message %d in mailbox %s" ENDL, msgnum + 1, mailbox); - fprintf(p, "Message-ID: " ENDL, msgnum, (unsigned int)ast_random(), mailbox, getpid(), host); + fprintf(p, "Message-ID: " ENDL, msgnum + 1, (unsigned int)ast_random(), mailbox, getpid(), host); if(imap) { /* additional information needed for IMAP searching */ fprintf(p, "X-Asterisk-VM-Message-Num: %d" ENDL, msgnum + 1); @@ -1930,7 +1930,7 @@ static void make_email_file(FILE *p, char *srcemail, struct ast_vm_user *vmu, in fprintf(p, "MIME-Version: 1.0" ENDL); if (attach_user_voicemail) { /* Something unique. */ - snprintf(bound, sizeof(bound), "voicemail_%d%s%d%d", msgnum, mailbox, getpid(), (unsigned int)ast_random()); + snprintf(bound, sizeof(bound), "voicemail_%d%s%d%d", msgnum + 1, mailbox, getpid(), (unsigned int)ast_random()); fprintf(p, "Content-Type: multipart/mixed; boundary=\"%s\"" ENDL ENDL ENDL, bound); @@ -1946,7 +1946,7 @@ static void make_email_file(FILE *p, char *srcemail, struct ast_vm_user *vmu, in memset(passdata, 0, vmlen); prep_email_sub_vars(ast, vmu, msgnum + 1, context, mailbox, cidnum, cidname, dur, date, passdata, vmlen, category); pbx_substitute_variables_helper(ast, emailbody, passdata, vmlen); - fprintf(p, "%s\r\n", passdata); + fprintf(p, "%s" ENDL, passdata); } else ast_log(LOG_WARNING, "Cannot allocate workspace for variable substitution\n"); ast_channel_free(ast); @@ -1978,19 +1978,19 @@ static void make_email_file(FILE *p, char *srcemail, struct ast_vm_user *vmu, in ast_log(LOG_DEBUG, "VOLGAIN: Stored at: %s.%s - Level: %.4f - Mailbox: %s\n", attach, format, vmu->volgain, mailbox); } fprintf(p, "--%s" ENDL, bound); - fprintf(p, "Content-Type: %s%s; name=\"msg%04d.%s\"" ENDL, ctype, format, msgnum, format); + fprintf(p, "Content-Type: %s%s; name=\"msg%04d.%s\"" ENDL, ctype, format, msgnum + 1, format); fprintf(p, "Content-Transfer-Encoding: base64" ENDL); fprintf(p, "Content-Description: Voicemail sound attachment." ENDL); - fprintf(p, "Content-Disposition: attachment; filename=\"msg%04d.%s\"" ENDL ENDL, msgnum, format); + fprintf(p, "Content-Disposition: attachment; filename=\"msg%04d.%s\"" ENDL ENDL, msgnum + 1, format); snprintf(fname, sizeof(fname), "%s.%s", attach, format); base_encode(fname, p); /* only attach if necessary */ if (imap && !strcmp(format, "gsm")) { fprintf(p, "--%s" ENDL, bound); - fprintf(p, "Content-Type: audio/x-gsm; name=\"msg%04d.%s\"" ENDL, msgnum, format); + fprintf(p, "Content-Type: audio/x-gsm; name=\"msg%04d.%s\"" ENDL, msgnum + 1, format); fprintf(p, "Content-Transfer-Encoding: base64" ENDL); fprintf(p, "Content-Description: Voicemail sound attachment." ENDL); - fprintf(p, "Content-Disposition: attachment; filename=\"msg%04d.gsm\"" ENDL ENDL, msgnum); + fprintf(p, "Content-Disposition: attachment; filename=\"msg%04d.gsm\"" ENDL ENDL, msgnum + 1); snprintf(fname, sizeof(fname), "%s.gsm", attach); base_encode(fname, p); } diff --git a/build_tools/make_buildopts_h b/build_tools/make_buildopts_h index 9970c0c0ba..203387e319 100755 --- a/build_tools/make_buildopts_h +++ b/build_tools/make_buildopts_h @@ -9,5 +9,9 @@ cat << END END TMP=`grep MENUSELECT_CFLAGS menuselect.makeopts | sed 's/MENUSELECT_CFLAGS\=//g' | sed 's/-D//g'` for x in ${TMP}; do - echo "#define ${x} 1" + echo "#define ${x} 1" done +if grep AST_DEVMODE makeopts | grep -q yes +then + echo "#define AST_DEVMODE 1" +fi diff --git a/configure b/configure index 594d27de21..1e8d865c0a 100755 --- a/configure +++ b/configure @@ -1,5 +1,5 @@ #! /bin/sh -# From configure.ac Revision: 57556 . +# From configure.ac Revision: 58320 . # Guess values for system-dependent variables and create Makefiles. # Generated by GNU Autoconf 2.60. # @@ -692,6 +692,7 @@ LN DOT STRIP WGET +RUBBER FETCH DOWNLOAD acx_pthread_config @@ -7401,6 +7402,47 @@ echo "${ECHO_T}no" >&6; } fi +# Extract the first word of "rubber", so it can be a program name with args. +set dummy rubber; ac_word=$2 +{ echo "$as_me:$LINENO: checking for $ac_word" >&5 +echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } +if test "${ac_cv_path_RUBBER+set}" = set; then + echo $ECHO_N "(cached) $ECHO_C" >&6 +else + case $RUBBER in + [\\/]* | ?:[\\/]*) + ac_cv_path_RUBBER="$RUBBER" # Let the user override the test with a path. + ;; + *) + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_exec_ext in '' $ac_executable_extensions; do + if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; }; then + ac_cv_path_RUBBER="$as_dir/$ac_word$ac_exec_ext" + echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 + break 2 + fi +done +done +IFS=$as_save_IFS + + test -z "$ac_cv_path_RUBBER" && ac_cv_path_RUBBER=":" + ;; +esac +fi +RUBBER=$ac_cv_path_RUBBER +if test -n "$RUBBER"; then + { echo "$as_me:$LINENO: result: $RUBBER" >&5 +echo "${ECHO_T}$RUBBER" >&6; } +else + { echo "$as_me:$LINENO: result: no" >&5 +echo "${ECHO_T}no" >&6; } +fi + + if test "${WGET}" != ":" ; then DOWNLOAD=${WGET} else @@ -34661,13 +34703,13 @@ LN!$LN$ac_delim DOT!$DOT$ac_delim STRIP!$STRIP$ac_delim WGET!$WGET$ac_delim +RUBBER!$RUBBER$ac_delim FETCH!$FETCH$ac_delim DOWNLOAD!$DOWNLOAD$ac_delim acx_pthread_config!$acx_pthread_config$ac_delim PTHREAD_CC!$PTHREAD_CC$ac_delim PTHREAD_LIBS!$PTHREAD_LIBS$ac_delim PTHREAD_CFLAGS!$PTHREAD_CFLAGS$ac_delim -AST_DEVMODE!$AST_DEVMODE$ac_delim _ACEOF if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then @@ -34709,6 +34751,7 @@ _ACEOF ac_delim='%!_!# ' for ac_last_try in false false false false false :; do cat >conf$$subs.sed <<_ACEOF +AST_DEVMODE!$AST_DEVMODE$ac_delim ALSA_LIB!$ALSA_LIB$ac_delim ALSA_INCLUDE!$ALSA_INCLUDE$ac_delim ALSA_DIR!$ALSA_DIR$ac_delim @@ -34805,7 +34848,6 @@ QT_LIB!$QT_LIB$ac_delim QT_INCLUDE!$QT_INCLUDE$ac_delim QT_DIR!$QT_DIR$ac_delim PBX_QT!$PBX_QT$ac_delim -RADIUS_LIB!$RADIUS_LIB$ac_delim _ACEOF if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 97; then @@ -34847,6 +34889,7 @@ _ACEOF ac_delim='%!_!# ' for ac_last_try in false false false false false :; do cat >conf$$subs.sed <<_ACEOF +RADIUS_LIB!$RADIUS_LIB$ac_delim RADIUS_INCLUDE!$RADIUS_INCLUDE$ac_delim RADIUS_DIR!$RADIUS_DIR$ac_delim PBX_RADIUS!$PBX_RADIUS$ac_delim @@ -34932,7 +34975,7 @@ CURL_CONFIG!$CURL_CONFIG$ac_delim LTLIBOBJS!$LTLIBOBJS$ac_delim _ACEOF - if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 83; then + if test `sed -n "s/.*$ac_delim\$/X/p" conf$$subs.sed | grep -c X` = 84; then break elif $ac_last_try; then { { echo "$as_me:$LINENO: error: could not make $CONFIG_STATUS" >&5 diff --git a/configure.ac b/configure.ac index fd166fc88e..0a0cb3e344 100644 --- a/configure.ac +++ b/configure.ac @@ -146,6 +146,7 @@ AC_PATH_PROG([LN], [ln], :) AC_PATH_PROG([DOT], [dot], :) AC_PATH_PROG([STRIP], [strip], :) AC_PATH_PROG([WGET], [wget], :) +AC_PATH_PROG([RUBBER], [rubber], :) if test "${WGET}" != ":" ; then DOWNLOAD=${WGET} else diff --git a/doc/00README.1st b/doc/00README.1st deleted file mode 100644 index c006d56a88..0000000000 --- a/doc/00README.1st +++ /dev/null @@ -1,74 +0,0 @@ -Files in the /doc directory: ----------------------------- -In addition to these files, there is a lot of documentation of various -configuration options in the sample configuration files, in the /configs -directory of your source code - -Start here ----------- -security.txt IMPORTANT INFORMATION ABOUT ASTERISK SECURITY -hardware.txt Hardware supported by Asterisk - -Configuration -------------- -configuration.txt Features in the configuration parser -extensions.txt Basics about the dialplan -extconfig.txt How to use databases for configuration of Asterisk (ARA) -ip-tos.txt About the IP Type Of Service settings -realtime.txt The Asterisk Realtime Architecture - database support -freetds.txt Information about the FreeTDS support -ael.txt Information about the Asterisk Extension Language - -Misc ----- -PEERING The General Peering Agreement for Dundi -ajam.txt About the HTTP-based manager interface -app_sms.txt How to configure the SMS application -asterisk.conf.txt Documentation of various options in asterisk.conf -callingpres.txt Settings for Caller ID presentation -billing.txt Call Data Record information -cliprompt.txt How to change the Asterisk CLI prompt -dundi.txt Dundi - a discovery protocol -enum.txt Enum support in Asterisk -ices.txt Integrating ICEcast streaming in Asterisk -jitterbuffer.txt About the IAX2 jitterbuffer implementation -math.txt About the math() application -mp3.txt About MP3 support in Asterisk -musiconhold-fpm.txt Free Music On Hold music -mysql.txt About MYSQL support in Asterisk -odbcstorage.txt Voicemail storage of messages in UnixODBC -privacy.txt Privacy enhancements in Asterisk -queuelog.txt Agent and queue logging -channelvariables.txt Channel variables -cdrdrivers.txt About CDR storage in various databases (needs update) -asterisk-mib.txt SNMP mib for Asterisk (net-snmp) -digium-mib.txt SNMP mib for Asterisk (net-snmp) - -Channel drivers ---------------- -misdn.txt The mISDN channel driver for ISDN BRI cards -h323.txt How to compile and configure the H.323 channel -chaniax.txt About the IAX2 protocol support in Asterisk -localchannel.txt The local channel is a "gosub" in the dialplan - -Portability ------------ -cygwin.txt Compiling Asterisk on CygWin platforms (Windows) - -For developers --------------- -See http://www.asterisk.org/developers for more information - -manager.txt About the AMI - Asterisk Manager Interface - for third party call control and PBX management -backtrace.txt How to produce a backtrace when Asterisk crashes -CODING-GUIDELINES Guidelines for developers -channels.txt What is a channel? -externalivr.txt Documentation of the protocol used in externalivr() -linkedlists.txt How to develop linked lists in Asterisk (old) -iax.txt About the IAX protocol -apps.txt About application development -model.txt About the call model in Asterisk (old) -modules.txt How Asterisk modules work -datastores.txt About channel data stores -speechrec.txt The Generic Speech Recognition API diff --git a/doc/PEERING b/doc/PEERING index c1f0b38312..ba05ffb9c6 100644 --- a/doc/PEERING +++ b/doc/PEERING @@ -1,3 +1,5 @@ +\begin{verbatim} + DIGIUM GENERAL PEERING AGREEMENT (TM) Version 1.0.0, September 2004 Copyright (C) 2004 Digium, Inc. @@ -497,3 +499,5 @@ member of the Peering System and be able to make Routes available in accordance with this GPA. DUNDi, IAX, Asterisk and GPA are trademarks of Digium, Inc. + +\end{verbatim} diff --git a/doc/ael.txt b/doc/ael.tex similarity index 79% rename from doc/ael.txt rename to doc/ael.tex index f72f2805bd..d675190ccf 100644 --- a/doc/ael.txt +++ b/doc/ael.tex @@ -1,5 +1,4 @@ -The Asterisk Extension Language - v 2 -===================================== +\section{Introduction} AEL is a specialized language intended purely for describing Asterisk dial plans. @@ -13,21 +12,22 @@ functionality. AEL is really the merger of 4 different 'languages', or syntaxes: - * The first and most obvious is the AEL syntax itself. A BNF is +\begin{itemize} + \item The first and most obvious is the AEL syntax itself. A BNF is provided near the end of this document. - * The second syntax is the Expression Syntax, which is normally + \item The second syntax is the Expression Syntax, which is normally handled by Asterisk extension engine, as expressions enclosed in - $[...]. The right hand side of assignments are wrapped in $[ ... ] + \$[...]. The right hand side of assignments are wrapped in \$[ ... ] by AEL, and so are the if and while expressions, among others. - * The third syntax is the Variable Reference Syntax, the stuff - enclosed in ${..} curly braces. It's a bit more involved than just + \item The third syntax is the Variable Reference Syntax, the stuff + enclosed in \${..} curly braces. It's a bit more involved than just putting a variable name in there. You can include one of dozens of 'functions', and their arguments, and there are even some string manipulation notation in there. - * The last syntax that underlies AEL, and is not used + \item The last syntax that underlies AEL, and is not used directly in AEL, is the Extension Language Syntax. The extension language is what you see in extensions.conf, and AEL compiles the higher level AEL language into extensions and @@ -36,14 +36,13 @@ AEL is really the merger of 4 different 'languages', or syntaxes: commands, of which one application call per step, or priority can be made. You can think of this as a "macro assembler" language, that AEL will compile into. - +\end{itemize} Any programmer of AEL should be familiar with it's syntax, of course, as well as the Expression syntax, and the Variable syntax. -************************** -* Asterisk in a Nutshell * -************************** + +\section{Asterisk in a Nutshell} Asterisk acts as a server. Devices involved in telephony, like Zapata cards, or Voip phones, all indicate some context that should be @@ -52,8 +51,7 @@ zapata.conf, etc. They all help describe a device, and they all specify a context to activate when somebody picks up a phone, or a call comes in from the phone company, or a voip phone, etc. -Contexts --------- +\subsection{Contexts} Contexts are a grouping of extensions. @@ -61,8 +59,7 @@ Contexts can also include other contexts. Think of it as a sort of merge operation at runtime, whereby the included context's extensions are added to the contexts making the inclusion. -Extensions and priorities -------------------------- +\subsection{Extensions and priorities} A Context contains zero or more Extensions. There are several predefined extensions. The "s" extension is the "start" extension, and @@ -94,8 +91,7 @@ The extensions can also contain "goto" or "jump" commands to skip to extensions in other contexts. Conditionals provide the ability to react to different stimuli, and there you have it. -Macros ------- +\subsection{Macros} Think of a macro as a combination of a context with one nameless extension, and a subroutine. It has arguments like a subroutine @@ -104,8 +100,7 @@ individual statements there are executed until it ends. At this point, execution returns to the next statement after the macro call. Macros can call other macros. And they work just like function calls. -Applications ------------- +\subsection{Applications} Application calls, like "Dial()", or "Hangup()", or "Answer()", are available for users to use to accomplish the work of the @@ -117,14 +112,11 @@ services. Hopefully, the above objects will allow you do anything you need to in the Asterisk environment! +\section{Getting Started} -******************* -* Getting Started * -******************* - -The AEL parser (pbx_ael.so) is completely separate from the module -that parses extensions.conf (pbx_config.so). To use AEL, the only -thing that has to be done is the module pbx_ael.so must be loaded by +The AEL parser (pbx\_ael.so) is completely separate from the module +that parses extensions.conf (pbx\_config.so). To use AEL, the only +thing that has to be done is the module pbx\_ael.so must be loaded by Asterisk. This will be done automatically if using 'autoload=yes' in /etc/asterisk/modules.conf. When the module is loaded, it will look for 'extensions.ael' in /etc/asterisk/. extensions.conf and @@ -133,9 +125,7 @@ each other if that is what is desired. Some users may want to keep extensions.conf for the features that are configured in the 'general' section of extensions.conf. ------------------------------- -- Reloading extensions.ael - ------------------------------- +Reloading extensions.ael To reload extensions.ael, the following command can be issued at the CLI: @@ -143,10 +133,7 @@ CLI: *CLI> ael reload - -************* -* Debugging * -************* +\section{Debugging} Right at this moment, the following commands are available, but do nothing: @@ -174,9 +161,7 @@ facilities to debug your file: 3. the standalone executable, "aelparse" built in the utils/ dir in the source. -***************************** -* About "aelparse" * -***************************** +\section{About "aelparse"} You can use the "aelparse" program to check your extensions.ael file before feeding it to asterisk. Wouldn't it be nice to eliminate @@ -188,20 +173,24 @@ spot in your PATH. aelparse has two optional arguments: --d - Override the normal location of the config file dir, (usually +\begin{itemize} + \item -d + \begin{itemize} + \item Override the normal location of the config file dir, (usually /etc/asterisk), and use the current directory instead as the config file dir. Aelparse will then expect to find the file "./extensions.ael" in the current directory, and any included files in the current directory as well. - --n - don't show all the function calls to set priorities and contexts + \end{itemize} + \item -n + \begin{itemize} + \item don't show all the function calls to set priorities and contexts within asterisk. It will just show the errors and warnings from the parsing and semantic checking phases. + \end{itemize} +\end{itemize} - -****************************** -* General Notes about Syntax * -****************************** +\section{General Notes about Syntax} Note that the syntax and style are now a little more free-form. The opening '{' (curly-braces) do not have to be on the same line as the @@ -211,10 +200,13 @@ be included on a single line. Whatever you think is best! You can just as easily say, +\begin{verbatim} if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } +\end{verbatim} as you can say: +\begin{verbatim} if(${x}=1) { NoOp(hello!); @@ -225,9 +217,11 @@ else NoOp(Goodbye!); goto s|12; } +\end{verbatim} or: +\begin{verbatim} if(${x}=1) { NoOp(hello!); goto s|3; @@ -235,33 +229,19 @@ if(${x}=1) { NoOp(Goodbye!); goto s|12; } +\end{verbatim} or: +\begin{verbatim} if (${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; } +\end{verbatim} -or even: - -if -(${x}=1) -{ -NoOp(hello!); -goto s|3; -} -else -{ -NoOp(Goodbye!); -goto s|12; -} - - -************ -* Keywords * -************ +\section{Keywords} The AEL keywords are case-sensitive. If an application name and a keyword overlap, there is probably good reason, and you should @@ -271,41 +251,38 @@ capitalized letter somewhere in its name. In the Asterisk extension language, application names are NOT case-sensitive. The following are keywords in the AEL language: - - * abstract - * context - * macro - * globals - * ignorepat - * switch - * if - * ifTime - * else - * random - * goto - * jump - * return - * break - * continue - * regexten - * hint - * for - * while - * case - * pattern - * default NOTE: the "default" keyword can be used as a context name, +\begin{itemize} + \item abstract + \item context + \item macro + \item globals + \item ignorepat + \item switch + \item if + \item ifTime + \item else + \item random + \item goto + \item jump + \item return + \item break + \item continue + \item regexten + \item hint + \item for + \item while + \item case + \item pattern + \item default NOTE: the "default" keyword can be used as a context name, for those who would like to do so. - * catch - * switches - * eswitches - * includes - + \item catch + \item switches + \item eswitches + \item includes +\end{itemize} - - -Procedural Interface and Internals -================================== +\section{Procedural Interface and Internals} AEL first parses the extensions.ael file into a memory structure representing the file. The entire file is represented by a tree of "pval" structures linked together. @@ -323,25 +300,19 @@ asterisk dialplan. The modularity of the design offers several opportunities for developers to simplify apps to generate dialplan data. - -========================= - AEL version 2 BNF -========================= - - +\subsection{AEL version 2 BNF} (hopefully, something close to bnf). First, some basic objects +\begin{verbatim} ------------------------ - a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]* a concatenation of up to 3 s. all characters encountered until the character that follows the in the grammar. - ------------------------- :== @@ -517,29 +488,27 @@ First, some basic objects :== 'includes' '{' '}' | 'includes' '{' '}' +\end{verbatim} -************************** -* AEL Example USAGE ***** -************************** -Comments -======== +\section{AEL Example USAGE} + +\subsection{Comments} Comments begin with // and end with the end of the line. Comments are removed by the lexical scanner, and will not be recognized in places where it is busy gathering expressions to wrap in -$[] , or inside application call argument lists. The safest place to put +\$[] , or inside application call argument lists. The safest place to put comments is after terminating semicolons, or on otherwise empty lines. -Context -======= +\subsection{Context} Contexts in AEL represent a set of extensions in the same way that they do in extensions.conf. - +\begin{verbatim} context default { } @@ -551,21 +520,20 @@ only be included by another context, and not "stand on its own". The current effect of this keyword is to prevent "goto " statements from being checked. - +\begin{verbatim} abstract context longdist { - _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); + _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US); } +\end{verbatim} - -Extensions -========== +\subsection{Extensions} To specify an extension in a context, the following syntax is used. If more than one application is be called in an extension, they can be listed in order inside of a block. - +\begin{verbatim} context default { 1234 => Playback(tt-monkeys); 8000 => { @@ -575,7 +543,7 @@ context default { }; _5XXX => NoOp(it's a pattern!); } - +\end{verbatim} Two optional items have been added to the AEL syntax, that allow the specification of hints, and a keyword, regexten, that will force the @@ -584,36 +552,38 @@ numbering of priorities to start at 2. The ability to make extensions match by CID is preserved in AEL; just use '/' and the CID number in the specification. See below. - +\begin{verbatim} context default { regexten _5XXX => NoOp(it's a pattern!); } +\end{verbatim} - - +\begin{verbatim} context default { hint(Sip/1) _5XXX => NoOp(it's a pattern!); } +\end{verbatim} - - +\begin{verbatim} context default { regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); } - +\end{verbatim} The regexten must come before the hint if they are both present. CID matching is done as with the extensions.conf file. Follow the extension name/number with a slash (/) and the number to match against the Caller ID: +\begin{verbatim} context zoombo { 819/7079953345 => { NoOp(hello, 3345); } } +\end{verbatim} In the above, the 819/7079953345 extension will only be matched if the CallerID is 7079953345, and the dialed number is 819. Hopefully you have @@ -621,13 +591,12 @@ another 819 extension defined for all those who wish 819, that are not so lucky as to have 7079953345 as their CallerID! -Includes -======== +\subsection{Includes} Contexts can be included in other contexts. All included contexts are listed within a single block. - +\begin{verbatim} context default { includes { local; @@ -635,13 +604,13 @@ context default { international; } } - +\end{verbatim} Time-limited inclusions can be specified, as in extensions.conf format, with the fields described in the wiki page Asterisk cmd GotoIfTime. - +\begin{verbatim} context default { includes { local; @@ -649,20 +618,19 @@ context default { international; } } +\end{verbatim} +\subsection{\#include} -#include -======== - -You can include other files with the #include "filepath" construct. - +You can include other files with the \#include "filepath" construct. +\begin{verbatim} #include "/etc/asterisk/testfor.ael" +\end{verbatim} - -An interesting property of the #include, is that you can use it almost +An interesting property of the \#include, is that you can use it almost anywhere in the .ael file. It is possible to include the contents of -a file in a macro, context, or even extension. The #include does not +a file in a macro, context, or even extension. The \#include does not have to occur at the beginning of a line. Included files can include other files, up to 50 levels deep. If the path provided in quotes is a relative path, the parser looks in the config file directory for the @@ -670,14 +638,13 @@ file (usually /etc/asterisk). -Dialplan Switches -================= +\subsection{Dialplan Switches} Switches are listed in their own block within a context. For clues as to what these are used for, see Asterisk - dual servers, and Asterisk config extensions.conf. - +\begin{verbatim} context default { switches { DUNDi/e164; @@ -687,43 +654,40 @@ context default { IAX2/context@${CURSERVER}; } } +\end{verbatim} - -Ignorepat -========= +\subsection{Ignorepat} ignorepat can be used to instruct channel drivers to not cancel dialtone upon receipt of a particular pattern. The most commonly used example is '9'. - +\begin{verbatim} context outgoing { ignorepat => 9; } +\end{verbatim} - - -Variables -========= +\subsection{Variables} Variables in Asterisk do not have a type, so to define a variable, it just has to be specified with a value. Global variables are set in their own block. - +\begin{verbatim} globals { CONSOLE=Console/dsp; TRUNK=Zap/g2; } - +\end{verbatim} Variables can be set within extensions as well. - +\begin{verbatim} context foo { 555 => { x=5; @@ -732,36 +696,35 @@ context foo { NoOp(x is ${x} and y is ${y} !); } } +\end{verbatim} - -NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow +NOTE: AEL wraps the right hand side of an assignment with \$[ ] to allow expressions to be used If this is unwanted, you can protect the right hand side from being wrapped by using the Set() application. Read the README.variables about the requirements and behavior -of $[ ] expressions. +of \$[ ] expressions. -NOTE: These things are wrapped up in a $[ ] expression: The while() test; +NOTE: These things are wrapped up in a \$[ ] expression: The while() test; the if() test; the middle expression in the for( x; y; z) statement -(the y expression); Assignments - the right hand side, so a = b -> Set(a=$[b]) +(the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b]) Writing to a dialplan function is treated the same as writing to a variable. - +\begin{verbatim} context blah { s => { CALLERID(name)=ChickenMan; NoOp(My name is ${CALLERID(name)} !); } } +\end{verbatim} - -Loops -===== +\subsection{Loops} AEL has implementations of 'for' and 'while' loops. - +\begin{verbatim} context loops { 1 => { for (x=0; ${x} < 3; x=${x} + 1) { @@ -776,16 +739,15 @@ context loops { } } } +\end{verbatim} +NOTE: The conditional expression (the "\${y} >= 0" above) is wrapped in + \$[ ] so it can be evaluated. NOTE: The for loop test expression + (the "\${x} < 3" above) is wrapped in \$[ ] so it can be evaluated. -NOTE: The conditional expression (the "${y} >= 0" above) is wrapped in - $[ ] so it can be evaluated. NOTE: The for loop test expression - (the "${x} < 3" above) is wrapped in $[ ] so it can be evaluated. - -Conditionals -============ +\subsection{Conditionals} AEL supports if and switch statements, like AEL, but adds ifTime, and random. Unlike the original AEL, though, you do NOT need to put curly @@ -793,7 +755,7 @@ braces around a single statement in the "true" branch of an if(), the random(), or an ifTime() statement. The if(), ifTime(), and random() statements allow optional else clause. - +\begin{verbatim} context conditional { _8XXX => { Dial(SIP/${EXTEN}); @@ -847,14 +809,14 @@ context conditional { } } } - +\end{verbatim} NOTE: The conditional expression in if() statements (the - "${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in - $[] for evaluation. + "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in + \$[] for evaluation. -NOTE: Neither the switch nor case values are wrapped in $[ ]; they can - be constants, or ${var} type references only. +NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can + be constants, or \${var} type references only. NOTE: AEL generates each case as a separate extension. case clauses with no terminating 'break', or 'goto', have a goto inserted, to @@ -866,7 +828,7 @@ NOTE: AEL introduces the ifTime keyword/statement, which works just Asterisk cmd GotoIfTime NOTE: The pattern statement makes sure the new extension that is - created has an '_' preceding it to make sure asterisk recognizes + created has an '\_' preceding it to make sure asterisk recognizes the extension name as a pattern. NOTE: Every character enclosed by the switch expression's parenthesis @@ -878,9 +840,7 @@ NOTE: NEW: Previous to version 0.13, the random statement used the the RAND() function instead, in the GotoIf application. -Break, Continue, and Return -=========================== - +\subsection{Break, Continue, and Return} Three keywords, break, continue, and return, are included in the syntax to provide flow of control to loops, and switches. @@ -898,12 +858,11 @@ context, or macro, and can be used anywhere. -goto, jump, and labels -====================== +\subsection{goto, jump, and labels} This is an example of how to do a goto in AEL. - +\begin{verbatim} context gotoexample { s => { begin: @@ -925,6 +884,7 @@ context gotoexample2 { goto gotoexample|s|begin; // go to label in different context } } +\end{verbatim} You can use the special label of "1" in the goto and jump statements. It means the "first" statement in the extension. I would @@ -938,7 +898,7 @@ extension[,priority][@context] If priority is absent, it defaults to "1". If context is not present, it is assumed to be the same as that which contains the "jump". - +\begin{verbatim} context gotoexample { s => { begin: @@ -960,6 +920,7 @@ context gotoexample2 { jump s@gotoexample; // go to label in different context } } +\end{verbatim} NOTE: goto labels follow the same requirements as the Goto() application, except the last value has to be a label. If the @@ -980,15 +941,14 @@ NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to -Macros -====== +\subsection{Macros} A macro is defined in its own block like this. The arguments to the macro are specified with the name of the macro. They are then referred to by that same name. A catch block can be specified to catch special extensions. - +\begin{verbatim} macro std-exten( ext , dev ) { Dial(${dev}/${ext},20); switch(${DIALSTATUS) { @@ -1004,26 +964,25 @@ macro std-exten( ext , dev ) { return; } } - +\end{verbatim} A macro is then called by preceding the macro name with an ampersand. Empty arguments can be passed simply with nothing between comments(0.11). - +\begin{verbatim} context example { _5XXX => &std-exten(${EXTEN}, "IAX2"); _6XXX => &std-exten(, "IAX2"); _7XXX => &std-exten(${EXTEN},); _8XXX => &std-exten(,); } +\end{verbatim} +\section{Examples} -Examples -======== - - +\begin{verbatim} context demo { s => { Wait(1); @@ -1067,117 +1026,121 @@ hangup: t => goto #|hangup; i => Playback(invalid); } +\end{verbatim} -Semantic Checks -=============== +\section{Semantic Checks} AEL, after parsing, but before compiling, traverses the dialplan tree, and makes several checks: - * Macro calls to non-existent macros. - * Macro calls to contexts. - * Macro calls with argument count not matching the definition. - * application call to macro. (missing the '&') - * application calls to "GotoIf", "GotoIfTime", "while", +\begin{itemize} + \item Macro calls to non-existent macros. + \item Macro calls to contexts. + \item Macro calls with argument count not matching the definition. + \item application call to macro. (missing the '\&') + \item application calls to "GotoIf", "GotoIfTime", "while", "endwhile", "Random", and "execIf", will generate a message to consider converting the call to AEL goto, while, etc. constructs. - * goto a label in an empty extension. - * goto a non-existent label, either a within-extension, + \item goto a label in an empty extension. + \item goto a non-existent label, either a within-extension, within-context, or in a different context, or in any included contexts. Will even check "sister" context references. - * All the checks done on the time values in the dial plan, are + \item All the checks done on the time values in the dial plan, are done on the time values in the ifTime() and includes times: o the time range has to have two times separated by a dash; o the times have to be in range of 0 to 24 hours. o The weekdays have to match the internal list, if they are provided; o the day of the month, if provided, must be in range of 1 to 31; o the month name or names have to match those in the internal list. - * (0.5) If an expression is wrapped in $[ ... ], and the compiler + \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler will wrap it again, a warning is issued. - * (0.5) If an expression had operators (you know, - +,-,*,/,%,!,etc), but no ${ } variables, a warning is + \item (0.5) If an expression had operators (you know, + +,-,*,/,%,!,etc), but no \${ } variables, a warning is issued. Maybe someone forgot to wrap a variable name? - * (0.12) check for duplicate context names. - * (0.12) check for abstract contexts that are not included by any context. - * (0.13) Issue a warning if a label is a numeric value. + \item (0.12) check for duplicate context names. + \item (0.12) check for abstract contexts that are not included by any context. + \item (0.13) Issue a warning if a label is a numeric value. +\end{itemize} There are a subset of checks that have been removed until the proposed AAL (Asterisk Argument Language) is developed and incorporated into Asterisk. These checks will be: - * (if the application argument analyzer is working: the presence +\begin{itemize} + \item (if the application argument analyzer is working: the presence of the 'j' option is reported as error. - * if options are specified, that are not available in an + \item if options are specified, that are not available in an application. - * if you specify too many arguments to an application. - * a required argument is not present in an application call. - * Switch-case using "known" variables that applications set, that + \item if you specify too many arguments to an application. + \item a required argument is not present in an application call. + \item Switch-case using "known" variables that applications set, that does not cover all the possible values. (a "default" case will solve this problem. Each "unhandled" value is listed. - * a Switch construct is used, which is uses a known variable, and + \item a Switch construct is used, which is uses a known variable, and the application that would set that variable is not called in the same extension. This is a warning only... - * Calls to applications not in the "applist" database (installed + \item Calls to applications not in the "applist" database (installed in /var/lib/asterisk/applist" on most systems). - * In an assignment statement, if the assignment is to a function, + \item In an assignment statement, if the assignment is to a function, the function name used is checked to see if it one of the currently known functions. A warning is issued if it is not. - +\end{itemize} Differences with the original version of AEL ============================================ - 1. The $[...] expressions have been enhanced to include the ==, ||, - and && operators. These operators are exactly equivalent to the - =, |, and & operators, respectively. Why? So the C, Java, C++ +\begin{enumerate} + \item The \$[...] expressions have been enhanced to include the ==, ||, + and \&\& operators. These operators are exactly equivalent to the + =, |, and \& operators, respectively. Why? So the C, Java, C++ hackers feel at home here. - 2. It is more free-form. The newline character means very little, + \item It is more free-form. The newline character means very little, and is pulled out of the white-space only for line numbers in error messages. - 3. It generates more error messages -- by this I mean that any + \item It generates more error messages -- by this I mean that any difference between the input and the grammar are reported, by file, line number, and column. - 4. It checks the contents of $[ ] expressions (or what will end up - being $[ ] expressions!) for syntax errors. It also does + \item It checks the contents of \$[ ] expressions (or what will end up + being \$[ ] expressions!) for syntax errors. It also does matching paren/bracket counts. - 5. It runs several semantic checks after the parsing is over, but + \item It runs several semantic checks after the parsing is over, but before the compiling begins, see the list above. - 6. It handles #include "filepath" directives. -- ALMOST + \item It handles \#include "filepath" directives. -- ALMOST anywhere, in fact. You could easily include a file in a context, in an extension, or at the root level. Files can be included in files that are included in files, down to 50 levels of hierarchy... - 7. Local Goto's inside Switch statements automatically have the + \item Local Goto's inside Switch statements automatically have the extension of the location of the switch statement appended to them. - 8. A pretty printer function is available within pbx_ael.so. - 9. In the utils directory, two standalone programs are supplied for + \item A pretty printer function is available within pbx\_ael.so. + \item In the utils directory, two standalone programs are supplied for debugging AEL files. One is called "aelparse", and it reads in the /etc/asterisk/extensions.ael file, and shows the results of syntax and semantic checking on stdout, and also shows the results of compilation to stdout. The other is "aelparse1", which uses the original ael compiler to do the same work, reading in "/etc/asterisk/extensions.ael", using the original - 'pbx_ael.so' instead. - 10. AEL supports the "jump" statement, and the "pattern" statement + 'pbx\_ael.so' instead. + \item AEL supports the "jump" statement, and the "pattern" statement in switch constructs. Hopefully these will be documented in the AEL README. - 11. Added the "return" keyword, which will jump to the end of an + \item Added the "return" keyword, which will jump to the end of an extension/Macro. - 12. Added the ifTime (