sysmocom
/
asterisk
11
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Another major doc directory update from IgorG. This patch includes 

- Many uses of the astlisting environment around verbatim text to ensure that
   it gets properly formatted and doesn't run off the page.
 - Update some things that have been deprecated.
 - Add escaping as needed
 - and more ...

(closes issue #10978)
Reported by: IgorG
Patches: 
      texdoc-85542-1.patch uploaded by IgorG (license 20)


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@85547 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Russell Bryant 2007-10-15 13:12:51 +00:00
parent 27031927cf
commit 4765cf4553
22 changed files with 641 additions and 459 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
apps/app_zapateller.c
View File

@ -53,7 +53,7 @@ static char *descrip =
" 'answer' - causes the line to be answered before playing the tone,\n" " 'answer' - causes the line to be answered before playing the tone,\n"
" 'nocallerid' - causes Zapateller to only play the tone if there is no\n" " 'nocallerid' - causes Zapateller to only play the tone if there is no\n"
" callerid information available. Options should be\n" " callerid information available. Options should be\n"
" separated by | characters\n\n" " separated by , characters\n\n"
" This application will set the following channel variable upon completion:\n" " This application will set the following channel variable upon completion:\n"
" ZAPATELLERSTATUS - This will contain the last action accomplished by the\n" " ZAPATELLERSTATUS - This will contain the last action accomplished by the\n"
" Zapateller application. Possible values include:\n" " Zapateller application. Possible values include:\n"

173
doc/tex/ael.tex
View File

@ -22,7 +22,7 @@ AEL is really the merger of 4 different 'languages', or syntaxes:
by AEL, and so are the if and while expressions, among others. by AEL, and so are the if and while expressions, among others.
\item The third syntax is the Variable Reference Syntax, the stuff \item The third syntax is the Variable Reference Syntax, the stuff
enclosed in \${..} curly braces. It's a bit more involved than just 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 putting a variable name in there. You can include one of dozens of
'functions', and their arguments, and there are even some string 'functions', and their arguments, and there are even some string
manipulation notation in there. manipulation notation in there.
@ -118,45 +118,47 @@ The AEL parser (pbx\_ael.so) is completely separate from the module
that parses extensions.conf (pbx\_config.so). To use AEL, the only 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 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 Asterisk. This will be done automatically if using 'autoload=yes' in
/etc/asterisk/modules.conf. When the module is loaded, it will look \path{/etc/asterisk/modules.conf}. When the module is loaded, it will look
for 'extensions.ael' in /etc/asterisk/. extensions.conf and for 'extensions.ael' in \path{/etc/asterisk/}. extensions.conf and
extensions.ael can be used in conjunction with extensions.ael can be used in conjunction with
each other if that is what is desired. Some users may want to keep 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' extensions.conf for the features that are configured in the 'general'
section of extensions.conf. section of extensions.conf.
Reloading extensions.ael
To reload extensions.ael, the following command can be issued at the To reload extensions.ael, the following command can be issued at the
CLI: CLI:
*CLI> ael reload *CLI> ael reload
\section{Debugging} \section{Debugging}
Right at this moment, the following commands are available, but do Right at this moment, the following commands are available, but do
nothing: nothing:
Enable AEL contexts debug Enable AEL contexts debug
*CLI> ael debug contexts
*CLI$>$ ael debug contexts
Enable AEL macros debug Enable AEL macros debug
*CLI> ael debug macros
*CLI$>$ ael debug macros
Enable AEL read debug Enable AEL read debug
*CLI> ael debug read
*CLI$>$ ael debug read
Enable AEL tokens debug Enable AEL tokens debug
*CLI> ael debug tokens
*CLI$>$ ael debug tokens
Disable AEL debug messages Disable AEL debug messages
*CLI> ael no debug
*CLI$>$ ael no debug
If things are going wrong in your dialplan, you can use the following If things are going wrong in your dialplan, you can use the following
facilities to debug your file: facilities to debug your file:
1. The messages log in /var/log/asterisk. (from the checks done at load time). 1. The messages log in \path{/var/log/asterisk}. (from the checks done at load time).
2. the "show dialplan" command in asterisk 2. the "show dialplan" command in asterisk
3. the standalone executable, "aelparse" built in the utils/ dir in the source. 3. the standalone executable, "aelparse" built in the utils/ dir in the source.
@ -177,7 +179,7 @@ aelparse has two optional arguments:
\item -d \item -d
\begin{itemize} \begin{itemize}
\item Override the normal location of the config file dir, (usually \item Override the normal location of the config file dir, (usually
/etc/asterisk), and use the current directory instead as the \path{/etc/asterisk}), and use the current directory instead as the
config file dir. Aelparse will then expect to find the file config file dir. Aelparse will then expect to find the file
"./extensions.ael" in the current directory, and any included "./extensions.ael" in the current directory, and any included
files in the current directory as well. files in the current directory as well.
@ -200,12 +202,13 @@ be included on a single line. Whatever you think is best!
You can just as easily say, You can just as easily say,
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
if(${x}=1) { NoOp(hello!); goto s,3; } else { NoOp(Goodbye!); goto s,12; } if(${x}=1) { NoOp(hello!); goto s,3; } else { NoOp(Goodbye!); goto s,12; }
\end{verbatim} \end{verbatim}
\end{astlisting}
as you can say: as you can say:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
if(${x}=1) if(${x}=1)
{ {
@ -218,9 +221,11 @@ else
goto s,12; goto s,12;
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
or: or:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
if(${x}=1) { if(${x}=1) {
NoOp(hello!); NoOp(hello!);
@ -230,9 +235,11 @@ if(${x}=1) {
goto s,12; goto s,12;
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
or: or:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
if (${x}=1) { if (${x}=1) {
NoOp(hello!); goto s,3; NoOp(hello!); goto s,3;
@ -240,6 +247,7 @@ if (${x}=1) {
NoOp(Goodbye!); goto s,12; NoOp(Goodbye!); goto s,12;
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Keywords} \section{Keywords}
@ -510,32 +518,33 @@ comments is after terminating semicolons, or on otherwise empty lines.
Contexts in AEL represent a set of extensions in the same way that Contexts in AEL represent a set of extensions in the same way that
they do in extensions.conf. they do in extensions.conf.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
} }
\end{verbatim}
\end{astlisting}
A context can be declared to be "abstract", in which case, this A context can be declared to be "abstract", in which case, this
declaration expresses the intent of the writer, that this context will declaration expresses the intent of the writer, that this context will
only be included by another context, and not "stand on its own". The only be included by another context, and not "stand on its own". The
current effect of this keyword is to prevent "goto " statements from current effect of this keyword is to prevent "goto " statements from
being checked. being checked.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
abstract context longdist { 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} \end{verbatim}
\end{astlisting}
\subsection{Extensions} \subsection{Extensions}
To specify an extension in a context, the following syntax is used. If 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 more than one application is be called in an extension, they can be
listed in order inside of a block. listed in order inside of a block.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
1234 => Playback(tt-monkeys); 1234 => Playback(tt-monkeys);
@ -547,6 +556,7 @@ context default {
_5XXX => NoOp(it's a pattern!); _5XXX => NoOp(it's a pattern!);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
Two optional items have been added to the AEL syntax, that allow the Two optional items have been added to the AEL syntax, that allow the
specification of hints, and a keyword, regexten, that will force the specification of hints, and a keyword, regexten, that will force the
@ -554,39 +564,45 @@ numbering of priorities to start at 2.
The ability to make extensions match by CID is preserved in The ability to make extensions match by CID is preserved in
AEL; just use '/' and the CID number in the specification. See below. AEL; just use '/' and the CID number in the specification. See below.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
regexten _5XXX => NoOp(it's a pattern!); regexten _5XXX => NoOp(it's a pattern!);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
hint(Sip/1) _5XXX => NoOp(it's a pattern!); hint(Sip/1) _5XXX => NoOp(it's a pattern!);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!); regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
The regexten must come before the hint if they are both present. 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 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: name/number with a slash (/) and the number to match against the Caller ID:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context zoombo context zoombo
{ {
819/7079953345 => { NoOp(hello, 3345); } 819/7079953345 => { NoOp(hello, 3345); }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
In the above, the 819/7079953345 extension will only be matched if the 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 CallerID is 7079953345, and the dialed number is 819. Hopefully you have
@ -599,6 +615,7 @@ as to have 7079953345 as their CallerID!
Contexts can be included in other contexts. All included contexts are Contexts can be included in other contexts. All included contexts are
listed within a single block. listed within a single block.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
includes { includes {
@ -608,11 +625,13 @@ context default {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
Time-limited inclusions can be specified, as in extensions.conf Time-limited inclusions can be specified, as in extensions.conf
format, with the fields described in the wiki page Asterisk cmd format, with the fields described in the wiki page Asterisk cmd
GotoIfTime. GotoIfTime.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
includes { includes {
@ -622,14 +641,17 @@ context default {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{\#include} \subsection{\#include}
You can include other files with the \#include "filepath" construct. You can include other files with the \#include "filepath" construct.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
#include "/etc/asterisk/testfor.ael" #include "/etc/asterisk/testfor.ael"
\end{verbatim} \end{verbatim}
\end{astlisting}
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 anywhere in the .ael file. It is possible to include the contents of
@ -637,7 +659,7 @@ 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 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 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 relative path, the parser looks in the config file directory for the
file (usually /etc/asterisk). file (usually \path{/etc/asterisk}).
@ -647,6 +669,7 @@ 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 to what these are used for, see Asterisk - dual servers, and Asterisk
config extensions.conf. config extensions.conf.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context default { context default {
switches { switches {
@ -658,20 +681,20 @@ context default {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Ignorepat} \subsection{Ignorepat}
ignorepat can be used to instruct channel drivers to not cancel ignorepat can be used to instruct channel drivers to not cancel
dialtone upon receipt of a particular pattern. The most commonly used dialtone upon receipt of a particular pattern. The most commonly used
example is '9'. example is '9'.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context outgoing { context outgoing {
ignorepat => 9; ignorepat => 9;
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Variables} \subsection{Variables}
@ -680,16 +703,18 @@ just has to be specified with a value.
Global variables are set in their own block. Global variables are set in their own block.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
globals { globals {
CONSOLE=Console/dsp; CONSOLE=Console/dsp;
TRUNK=Zap/g2; TRUNK=Zap/g2;
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
Variables can be set within extensions as well. Variables can be set within extensions as well.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context foo { context foo {
555 => { 555 => {
@ -700,6 +725,7 @@ context foo {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
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 expressions to be used If this is unwanted, you can protect the right hand
@ -713,6 +739,7 @@ the if() test; the middle expression in the for( x; y; z) statement
Writing to a dialplan function is treated the same as writing to a variable. Writing to a dialplan function is treated the same as writing to a variable.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context blah { context blah {
s => { s => {
@ -721,9 +748,11 @@ context blah {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
You can declare variables in Macros, as so: You can declare variables in Macros, as so:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
Macro myroutine(firstarg, secondarg) Macro myroutine(firstarg, secondarg)
{ {
@ -731,6 +760,7 @@ Macro myroutine(firstarg, secondarg)
NoOp(Myvar is set to ${myvar}); NoOp(Myvar is set to ${myvar});
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Local Variables} \subsection{Local Variables}
@ -744,6 +774,7 @@ This includes the ARG1, ARG2, etc variables.
Users can declare their own local variables by using the keyword 'local' Users can declare their own local variables by using the keyword 'local'
before setting them to a value; before setting them to a value;
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
Macro myroutine(firstarg, secondarg) Macro myroutine(firstarg, secondarg)
{ {
@ -751,12 +782,13 @@ Macro myroutine(firstarg, secondarg)
NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
In the above example, Myvar, firstarg, and secondarg are all local variables, In the above example, Myvar, firstarg, and secondarg are all local variables,
and will not be visible to the calling code, be it an extension, or another Macro. and will not be visible to the calling code, be it an extension, or another Macro.
If you need to make a local variable within the Set() application, you can do it this way: If you need to make a local variable within the Set() application, you can do it this way:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
Macro myroutine(firstarg, secondarg) Macro myroutine(firstarg, secondarg)
{ {
@ -764,12 +796,12 @@ Macro myroutine(firstarg, secondarg)
NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg}); NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Loops} \subsection{Loops}
AEL has implementations of 'for' and 'while' loops. AEL has implementations of 'for' and 'while' loops.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context loops { context loops {
1 => { 1 => {
@ -786,8 +818,9 @@ context loops {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
NOTE: The conditional expression (the "\${y} $>$= 0" above) is wrapped in NOTE: The conditional expression (the "\$\{y\} $>$= 0" above) is wrapped in
\$[ ] so it can be evaluated. NOTE: The for loop test expression \$[ ] so it can be evaluated. NOTE: The for loop test expression
(the "\${x} $<$ 3" above) is wrapped in \$[ ] so it can be evaluated. (the "\${x} $<$ 3" above) is wrapped in \$[ ] so it can be evaluated.
@ -801,6 +834,7 @@ braces around a single statement in the "true" branch of an if(), the
random(), or an ifTime() statement. The if(), ifTime(), and random() random(), or an ifTime() statement. The if(), ifTime(), and random()
statements allow optional else clause. statements allow optional else clause.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context conditional { context conditional {
_8XXX => { _8XXX => {
@ -808,15 +842,15 @@ context conditional {
if ("${DIALSTATUS}" = "BUSY") if ("${DIALSTATUS}" = "BUSY")
{ {
NoOp(yessir); NoOp(yessir);
Voicemail(${EXTEN}|b); Voicemail(${EXTEN},b);
} }
else else
Voicemail(${EXTEN}|u); Voicemail(${EXTEN},u);
ifTime (14:00-25:00|sat-sun|*|*) ifTime (14:00-25:00,sat-sun,*,*)
Voicemail(${EXTEN}|b); Voicemail(${EXTEN},b);
else else
{ {
Voicemail(${EXTEN}|u); Voicemail(${EXTEN},u);
NoOp(hi, there!); NoOp(hi, there!);
} }
random(51) NoOp(This should appear 51% of the time); random(51) NoOp(This should appear 51% of the time);
@ -856,13 +890,14 @@ context conditional {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
NOTE: The conditional expression in if() statements (the NOTE: The conditional expression in if() statements (the
"\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in "\$\{DIALSTATUS\}" = "BUSY" above) is wrapped by the compiler in
\$[] for evaluation. \$[] for evaluation.
NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can
be constants, or \${var} type references only. be constants, or \$\{var\} type references only.
NOTE: AEL generates each case as a separate extension. case clauses NOTE: AEL generates each case as a separate extension. case clauses
with no terminating 'break', or 'goto', have a goto inserted, to with no terminating 'break', or 'goto', have a goto inserted, to
@ -908,6 +943,7 @@ context, or macro, and can be used anywhere.
This is an example of how to do a goto in AEL. This is an example of how to do a goto in AEL.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context gotoexample { context gotoexample {
s => { s => {
@ -917,20 +953,21 @@ begin:
goto begin; // go to label in same extension goto begin; // go to label in same extension
} }
3 => { 3 => {
goto s|begin; // go to label in different extension goto s,begin; // go to label in different extension
} }
4 => { 4 => {
goto gotoexample|s|begin; // overkill go to label in same context goto gotoexample,s,begin; // overkill go to label in same context
} }
} }
context gotoexample2 { context gotoexample2 {
s => { s => {
end: end:
goto gotoexample|s|begin; // go to label in different context goto gotoexample,s,begin; // go to label in different context
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
You can use the special label of "1" in the goto and jump You can use the special label of "1" in the goto and jump
statements. It means the "first" statement in the extension. I would statements. It means the "first" statement in the extension. I would
@ -944,6 +981,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 "1". If context is not present, it is assumed to be the same as that
which contains the "jump". which contains the "jump".
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context gotoexample { context gotoexample {
s => { s => {
@ -967,25 +1005,20 @@ context gotoexample2 {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
NOTE: goto labels follow the same requirements as the Goto() NOTE: goto labels follow the same requirements as the Goto()
application, except the last value has to be a label. If the application, except the last value has to be a label. If the
label does not exist, you will have run-time errors. If the label does not exist, you will have run-time errors. If the
label exists, but in a different extension, you have to specify label exists, but in a different extension, you have to specify
both the extension name and label in the goto, as in: goto s|z; both the extension name and label in the goto, as in: goto s,z;
if the label is in a different context, you specify if the label is in a different context, you specify
context|extension|label. There is a note about using goto's in a context,extension,label. There is a note about using goto's in a
switch statement below... switch statement below...
NOTE AEL introduces the special label "1", which is the beginning NOTE AEL introduces the special label "1", which is the beginning
context number for most extensions. context number for most extensions.
NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to
separate the items in the target address. You can't have a mix,
though, of '|' and ',' in the target. It's either one, or the other.
\subsection{Macros} \subsection{Macros}
@ -994,15 +1027,16 @@ 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 to by that same name. A catch block can be specified to catch special
extensions. extensions.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
macro std-exten( ext , dev ) { macro std-exten( ext , dev ) {
Dial(${dev}/${ext},20); Dial(${dev}/${ext},20);
switch(${DIALSTATUS) { switch(${DIALSTATUS) {
case BUSY: case BUSY:
Voicemail(b${ext}); Voicemail(${ext},b);
break; break;
default: default:
Voicemail(u${ext}); Voicemail(${ext},u);
} }
catch a { catch a {
@ -1011,11 +1045,13 @@ macro std-exten( ext , dev ) {
} }
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
A macro is then called by preceding the macro name with an A macro is then called by preceding the macro name with an
ampersand. Empty arguments can be passed simply with nothing between ampersand. Empty arguments can be passed simply with nothing between
comments(0.11). comments(0.11).
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context example { context example {
_5XXX => &std-exten(${EXTEN}, "IAX2"); _5XXX => &std-exten(${EXTEN}, "IAX2");
@ -1024,10 +1060,12 @@ context example {
_8XXX => &std-exten(,); _8XXX => &std-exten(,);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Examples} \section{Examples}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
context demo { context demo {
s => { s => {
@ -1045,34 +1083,35 @@ instructions:
} }
2 => { 2 => {
Background(demo-moreinfo); Background(demo-moreinfo);
goto s|instructions; goto s,instructions;
} }
3 => { 3 => {
LANGUAGE()=fr; LANGUAGE()=fr;
goto s|restart; goto s,restart;
} }
500 => { 500 => {
Playback(demo-abouttotry); Playback(demo-abouttotry);
Dial(IAX2/guest@misery.digium.com); Dial(IAX2/guest@misery.digium.com);
Playback(demo-nogo); Playback(demo-nogo);
goto s|instructions; goto s,instructions;
} }
600 => { 600 => {
Playback(demo-echotest); Playback(demo-echotest);
Echo(); Echo();
Playback(demo-echodone); Playback(demo-echodone);
goto s|instructions; goto s,instructions;
} }
# => { # => {
hangup: hangup:
Playback(demo-thanks); Playback(demo-thanks);
Hangup(); Hangup();
} }
t => goto #|hangup; t => goto #,hangup;
i => Playback(invalid); i => Playback(invalid);
} }
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Semantic Checks} \section{Semantic Checks}
@ -1128,7 +1167,7 @@ These checks will be:
the application that would set that variable is not called in the application that would set that variable is not called in
the same extension. This is a warning only... the same extension. This is a warning only...
\item 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 \path{/var/lib/asterisk/applist}" on most systems).
\item 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 the function name used is checked to see if it one of the
currently known functions. A warning is issued if it is not. currently known functions. A warning is issued if it is not.
@ -1137,9 +1176,9 @@ These checks will be:
\section{Differences with the original version of AEL} \section{Differences with the original version of AEL}
\begin{enumerate} \begin{enumerate}
\item The \$[...] expressions have been enhanced to include the ==, ||, \item The \$[...] expressions have been enhanced to include the ==, $|$$|$,
and \&\& operators. These operators are exactly equivalent to the and \&\& operators. These operators are exactly equivalent to the
=, |, and \& operators, respectively. Why? So the C, Java, C++ =, $|$, and \& operators, respectively. Why? So the C, Java, C++
hackers feel at home here. hackers feel at home here.
\item 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 and is pulled out of the white-space only for line numbers in
@ -1161,19 +1200,19 @@ These checks will be:
\item A pretty printer function is available within pbx\_ael.so. \item A pretty printer function is available within pbx\_ael.so.
\item In the utils directory, two standalone programs are supplied for \item In the utils directory, two standalone programs are supplied for
debugging AEL files. One is called "aelparse", and it reads in debugging AEL files. One is called "aelparse", and it reads in
the /etc/asterisk/extensions.ael file, and shows the results of the \path{/etc/asterisk/extensions.ael} file, and shows the results of
syntax and semantic checking on stdout, and also shows the syntax and semantic checking on stdout, and also shows the
results of compilation to stdout. The other is "aelparse1", results of compilation to stdout. The other is "aelparse1",
which uses the original ael compiler to do the same work, which uses the original ael compiler to do the same work,
reading in "/etc/asterisk/extensions.ael", using the original reading in "\path{/etc/asterisk/extensions.ael}", using the original
'pbx\_ael.so' instead. 'pbx\_ael.so' instead.
\item AEL supports the "jump" statement, and the "pattern" statement \item AEL supports the "jump" statement, and the "pattern" statement
in switch constructs. Hopefully these will be documented in the in switch constructs. Hopefully these will be documented in the
AEL README. AEL README.
\item 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. extension/Macro.
\item Added the ifTime ($<$time range$>$|$<$days of week$>$|$<$days of \item Added the ifTime ($<$time range$>$$|$$<$days of week$>$$|$$<$days of
month$>$|$<$months$>$ ) {} [else {}] construct, which executes much month$>$$|$$<$months$>$ ) {} [else {}] construct, which executes much
like an if () statement, but the decision is based on the like an if () statement, but the decision is based on the
current time, and the time spec provided in the ifTime. See the current time, and the time spec provided in the ifTime. See the
example above. (Note: all the other time-dependent Applications example above. (Note: all the other time-dependent Applications
@ -1216,15 +1255,15 @@ These checks will be:
\section{Hints and Bugs} \section{Hints and Bugs}
The safest way to check for a null strings is to say \$[ "\${x}" = The safest way to check for a null strings is to say \$[ "\$\{x\}" =
"" ] The old way would do as shell scripts often do, and append "" ] The old way would do as shell scripts often do, and append
something on both sides, like this: \$[ \${x}foo = foo ]. The something on both sides, like this: \$[ \$\{x\}foo = foo ]. The
trouble with the old way, is that, if x contains any spaces, then trouble with the old way, is that, if x contains any spaces, then
problems occur, usually syntax errors. It is better practice and problems occur, usually syntax errors. It is better practice and
safer wrap all such tests with double quotes! Also, there are now safer wrap all such tests with double quotes! Also, there are now
some functions that can be used in a variable reference, some functions that can be used in a variable reference,
ISNULL(), and LEN(), that can be used to test for an empty string: ISNULL(), and LEN(), that can be used to test for an empty string:
\${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ]. \$\{ISNULL(\$\{x\})\} or \$[ \$\{LEN(\$\{x\})\} = 0 ].
Assignment vs. Set(). Keep in mind that setting a variable to Assignment vs. Set(). Keep in mind that setting a variable to
value can be done two different ways. If you choose say 'x=y;', value can be done two different ways. If you choose say 'x=y;',
@ -1248,7 +1287,7 @@ available through AEL, via:
\item Applications: See Asterisk - documentation of application \item Applications: See Asterisk - documentation of application
commands commands
\item Functions: Functions were implemented inside \${ .. } variable \item Functions: Functions were implemented inside \$\{ .. \} variable
references, and supply many useful capabilities. references, and supply many useful capabilities.
\item Expressions: An expression evaluation engine handles items \item Expressions: An expression evaluation engine handles items

96
doc/tex/ajam.tex
View File

@ -1,85 +1,97 @@
\section{Asynchronous Javascript Asterisk Manger (AJAM)} \section{Asynchronous Javascript Asterisk Manger (AJAM)}
AJAM is a new technology which allows web browsers or other HTTP enabled AJAM is a new technology which allows web browsers or other HTTP enabled
applications and web pages to directly access the Asterisk Manger applications and web pages to directly access the Asterisk Manger
Interface (AMI) via HTTP. Setting up your server to process AJAM Interface (AMI) via HTTP. Setting up your server to process AJAM
involves a few steps: involves a few steps:
\subsection{Setup the Asterisk HTTP server} \subsection{Setup the Asterisk HTTP server}
\begin{enumerate} \begin{enumerate}
\item Uncomment the line "enabled=yes" in /etc/asterisk/http.conf to enable \item Uncomment the line "enabled=yes" in \path{/etc/asterisk/http.conf} to enable
Asterisk's builtin micro HTTP server. Asterisk's builtin micro HTTP server.
\item If you want Asterisk to actually deliver simple HTML pages, CSS, \item If you want Asterisk to actually deliver simple HTML pages, CSS,
javascript, etc. you should uncomment "enablestatic=yes" javascript, etc. you should uncomment "enablestatic=yes"
\item Adjust your "bindaddr" and "bindport" settings as appropriate for \item Adjust your "bindaddr" and "bindport" settings as appropriate for
your desired accessibility your desired accessibility
\item Adjust your "prefix" if appropriate, which must be the beginning of \item Adjust your "prefix" if appropriate, which must be the beginning of
any URI on the server to match. The default is "asterisk" and the any URI on the server to match. The default is "asterisk" and the
rest of these instructions assume that value. rest of these instructions assume that value.
\end{enumerate} \end{enumerate}
\subsection{Allow Manager Access via HTTP} \subsection{Allow Manager Access via HTTP}
\begin{enumerate} \begin{enumerate}
\item Make sure you have both "enabled = yes" and "webenabled = yes" setup \item Make sure you have both "enabled = yes" and "webenabled = yes" setup
in /etc/asterisk/manager.conf in \path{/etc/asterisk/manager.conf}
\item You may also use "httptimeout" to set a default timeout for HTTP \item You may also use "httptimeout" to set a default timeout for HTTP
connections. connections.
\item Make sure you have a manager username/secret \item Make sure you have a manager username/secret
\end{enumerate} \end{enumerate}
Once those configurations are complete you can reload or restart Once those configurations are complete you can reload or restart
Asterisk and you should be able to point your web browser to specific Asterisk and you should be able to point your web browser to specific
URI's which will allow you to access various web functions. A complete URI's which will allow you to access various web functions. A complete
list can be found by typing "show http" at the Asterisk CLI. list can be found by typing "http show status" at the Asterisk CLI.
examples: examples:
\begin{astlisting}
http://localhost:8088/asterisk/manager?action=login\&username=foo\&secret=bar \begin{verbatim}
http://localhost:8088/asterisk/manager?action=login&username=foo&secret=bar
This logs you into the manager interface's "HTML" view. Once you're \end{verbatim}
logged in, Asterisk stores a cookie on your browser (valid for the \end{astlisting}
length of httptimeout) which is used to connect to the same session. This logs you into the manager interface's "HTML" view. Once you're
logged in, Asterisk stores a cookie on your browser (valid for the
length of httptimeout) which is used to connect to the same session.
\begin{astlisting}
\begin{verbatim}
http://localhost:8088/asterisk/rawman?action=status http://localhost:8088/asterisk/rawman?action=status
\end{verbatim}
Assuming you've already logged into manager, this URI will give you a \end{astlisting}
Assuming you've already logged into manager, this URI will give you a
"raw" manager output for the "status" command. "raw" manager output for the "status" command.
\begin{astlisting}
\begin{verbatim}
http://localhost:8088/asterisk/mxml?action=status http://localhost:8088/asterisk/mxml?action=status
\end{verbatim}
This will give you the same status view but represented as AJAX data, \end{astlisting}
theoretically compatible with RICO (http://www.openrico.org). This will give you the same status view but represented as AJAX data,
theoretically compatible with RICO (\url{http://www.openrico.org}).
\begin{astlisting}
\begin{verbatim}
http://localhost:8088/asterisk/static/ajamdemo.html http://localhost:8088/asterisk/static/ajamdemo.html
\end{verbatim}
If you have enabled static content support and have done a make install, \end{astlisting}
Asterisk will serve up a demo page which presents a live, but very If you have enabled static content support and have done a make install,
basic, "astman" like interface. You can login with your username/secret Asterisk will serve up a demo page which presents a live, but very
for manager and have a basic view of channels as well as transfer and basic, "astman" like interface. You can login with your username/secret
for manager and have a basic view of channels as well as transfer and
hangup calls. It's only tested in Firefox, but could probably be made hangup calls. It's only tested in Firefox, but could probably be made
to run in other browsers as well. to run in other browsers as well.
A sample library (astman.js) is included to help ease the creation of A sample library (astman.js) is included to help ease the creation of
manager HTML interfaces. manager HTML interfaces.
Note that for the demo, there is no need for *any* external web server. Note that for the demo, there is no need for *any* external web server.
\subsection{Integration with other web servers} \subsection{Integration with other web servers}
Asterisk's micro HTTP server is *not* designed to replace a general Asterisk's micro HTTP server is *not* designed to replace a general
purpose web server and it is intentionally created to provide only the purpose web server and it is intentionally created to provide only the
minimal interfaces required. Even without the addition of an external minimal interfaces required. Even without the addition of an external
web server, one can use Asterisk's interfaces to implement screen pops web server, one can use Asterisk's interfaces to implement screen pops
and similar tools pulling data from other web servers using iframes, and similar tools pulling data from other web servers using iframes,
div's etc. If you want to integrate CGI's, databases, PHP, etc. you div's etc. If you want to integrate CGI's, databases, PHP, etc. you
will likely need to use a more traditional web server like Apache and will likely need to use a more traditional web server like Apache and
link in your Asterisk micro HTTP server with something like this: link in your Asterisk micro HTTP server with something like this:
\begin{astlisting}
\begin{verbatim}
ProxyPass /asterisk http://localhost:8088/asterisk ProxyPass /asterisk http://localhost:8088/asterisk
\end{verbatim}
\end{astlisting}

33
doc/tex/app-sms.tex
View File

@ -143,19 +143,21 @@ exten = _X.,3,Hangup
UK this call is from a CLI of 080058752X0 where X is the sub address. UK this call is from a CLI of 080058752X0 where X is the sub address.
As such a typical usage in the extensions.conf at the point of As such a typical usage in the extensions.conf at the point of
handling an incoming call is: handling an incoming call is:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1) exten = _X./8005875290,1,Goto(smsmtrx,${EXTEN},1)
exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):8:1},1) exten = _X./_80058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):8:1},1)
\end{verbatim} \end{verbatim}
\end{astlisting}
Alternatively, if you have the correct national prefix on incoming Alternatively, if you have the correct national prefix on incoming
CLI, e.g. using zaphfc, you might use: CLI, e.g. using zaphfc, you might use:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1) exten = _X./08005875290,1,Goto(smsmtrx,${EXTEN},1)
exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1) exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1)
\end{verbatim} \end{verbatim}
\end{astlisting}
smsmorx is normally accessed by a call from a local sip device smsmorx is normally accessed by a call from a local sip device
connected to a Magic Messenger. It could however by that you are connected to a Magic Messenger. It could however by that you are
@ -164,11 +166,12 @@ exten = _X./_080058752[0-8]0,1,Goto(smsmtrx,${EXTEN}-${CALLERID(num):9:1},1)
SMSC number that would be dialed is 1709400X where X is the caller sub SMSC number that would be dialed is 1709400X where X is the caller sub
address. As such typical usage in extension.config at the point of address. As such typical usage in extension.config at the point of
handling a call from a sip phone is: handling a call from a sip phone is:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten = 17094009,1,Goto(smsmorx,${CALLERID(num)},1) exten = 17094009,1,Goto(smsmorx,${CALLERID(num)},1)
exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1) exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Using smsq} \section{Using smsq}
@ -181,7 +184,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
smsq 0123456789 This is a test to 0123456789 smsq 0123456789 This is a test to 0123456789
This would create a queue file for a mobile originated TX message in This would create a queue file for a mobile originated TX message in
queue 0 to send the text "This is a test to 0123456789" to 0123456789. queue 0 to send the text "This is a test to 0123456789" to 0123456789.
It would then place a file in the /var/spool/asterisk/outgoing It would then place a file in the \path{/var/spool/asterisk/outgoing}
directory to initiate a call to 17094009 (the default message centre directory to initiate a call to 17094009 (the default message centre
in smsq) attached to application SMS with argument of the queue name in smsq) attached to application SMS with argument of the queue name
(0). (0).
@ -191,10 +194,10 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
connect to the message centre or device and actually send the pending connect to the message centre or device and actually send the pending
message(s). message(s).
Using --process, smsq can however be used on received queues to run a Using \verb!--process!, smsq can however be used on received queues to run a
command for each file (matching the queue if specified) with various command for each file (matching the queue if specified) with various
environment variables set based on the message (see below); environment variables set based on the message (see below);
smsq options:- smsq options:
\begin{verbatim} \begin{verbatim}
--help --help
Show help text Show help text
@ -341,14 +344,14 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
Note that when smsq attempts to make a file in Note that when smsq attempts to make a file in
/var/spool/asterisk/outgoing, it checks if there is already a call \path{/var/spool/asterisk/outgoing}, it checks if there is already a call
queued for that queue. It will try several filenames, up to the queued for that queue. It will try several filenames, up to the
--concurrent setting. If these files exist, then this means Asterisk \verb!--concurrent! setting. If these files exist, then this means Asterisk
is already queued to send all messages for that queue, and so Asterisk is already queued to send all messages for that queue, and so Asterisk
should pick up the message just queued. However, this alone could should pick up the message just queued. However, this alone could
create a race condition, so if the files exist then smsq will wait up create a race condition, so if the files exist then smsq will wait up
to 3 seconds to confirm it still exists or if the queued messages have to 3 seconds to confirm it still exists or if the queued messages have
been sent already. The --no-wait turns off this behaviour. Basically, been sent already. The \verb!--no-wait! turns off this behaviour. Basically,
this means that if you have a lot of messages to send all at once, this means that if you have a lot of messages to send all at once,
Asterisk will not make unlimited concurrent calls to the same message Asterisk will not make unlimited concurrent calls to the same message
centre or device for the same queue. This is because it is generally centre or device for the same queue. This is because it is generally
@ -361,7 +364,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
queued message it finds. A outgoing call will normally send all queued queued message it finds. A outgoing call will normally send all queued
messages for that queue. One way to use smsq would be to run with no messages for that queue. One way to use smsq would be to run with no
queue name (so any queue) every minute or every few seconds to send queue name (so any queue) every minute or every few seconds to send
pending message. This is not normally necessary unless --no-dial is pending message. This is not normally necessary unless \verb!--no-dial! is
selected. Note that smsq does only check motx or mttx depending on the selected. Note that smsq does only check motx or mttx depending on the
options selected, so it would need to be called twice as a general options selected, so it would need to be called twice as a general
check. check.
@ -369,7 +372,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
UTF-8 is used to parse command line arguments for user data, and is UTF-8 is used to parse command line arguments for user data, and is
the default when reading a file. If an invalid UTF-8 sequence is the default when reading a file. If an invalid UTF-8 sequence is
found, it is treated as UCS-1 data (i.e, as is). found, it is treated as UCS-1 data (i.e, as is).
The --process option causes smsq to scan the specified queue (default The \verb!--process! option causes smsq to scan the specified queue (default
is mtrx) for messages (matching the queue specified, or any if queue is mtrx) for messages (matching the queue specified, or any if queue
not specified) and run a command and delete the file. The command is not specified) and run a command and delete the file. The command is
run with a number of environment variables set as follows. Note that run with a number of environment variables set as follows. Note that
@ -404,10 +407,10 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
\section{File formats} \section{File formats}
By default all queues are held in a director /var/spool/asterisk/sms. By default all queues are held in a director \path{/var/spool/asterisk/sms}.
Within this directory are sub directories mtrx, mttx, morx, motx which Within this directory are sub directories mtrx, mttx, morx, motx which
hold the received messages and the messages ready to send. Also, hold the received messages and the messages ready to send. Also,
/var/log/asterisk/sms is a log file of all messages handled. \path{/var/log/asterisk/sms} is a log file of all messages handled.
The file name in each queue directory starts with the queue parameter The file name in each queue directory starts with the queue parameter
to SMS which is normally the CLI used for an outgoing message or the to SMS which is normally the CLI used for an outgoing message or the
@ -424,7 +427,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
UTF-8. The user data (ud) field is treated as being UTF-8 encoded UTF-8. The user data (ud) field is treated as being UTF-8 encoded
unless the DCS is specified indicating 8 bit format. If 8 bit format unless the DCS is specified indicating 8 bit format. If 8 bit format
is specified then the user data is sent as is. is specified then the user data is sent as is.
The keywords are as follows:- The keywords are as follows:
\begin{verbatim} \begin{verbatim}
oa Originating address oa Originating address
The phone number from which the message came The phone number from which the message came
@ -450,7 +453,7 @@ exten = _1709400[0-8],1,Goto(smsmorx,${CALLERID(num)}-{EXTEN:7:1},1)
Present on mobile originated messages, added by default if absent Present on mobile originated messages, added by default if absent
srr srr
0 or 1 for status report request 0 or 1 for status report request
Does not work in UK yet, not implemented in app\_sms yet Does not work in UK yet, not implemented in app_sms yet
rp rp
0 or 1 return path 0 or 1 return path
See GSM specs for details See GSM specs for details

16
doc/tex/billing.tex
View File

@ -8,11 +8,11 @@
\item ForkCDR - Save current CDR and start a new CDR for this call \item ForkCDR - Save current CDR and start a new CDR for this call
\item Authenticate - Authenticates and sets the account code \item Authenticate - Authenticates and sets the account code
\item SetCDRUserField - Set CDR user field \item SetCDRUserField - Set CDR user field
\item AppendCDRUserField - Append data to CDR User field \item AppendCDRUserField - Append data to CDR User field
\end{itemize} \end{itemize}
For more information, use the "core show application <application>" command. For more information, use the "core show application $<$application$>$" command.
You can set default account codes and AMA flags for devices in You can set default account codes and AMA flags for devices in
channel configuration files, like sip.conf, iax.conf etc. channel configuration files, like sip.conf, iax.conf etc.
\section{Fields of the CDR in Asterisk} \section{Fields of the CDR in Asterisk}
@ -33,15 +33,15 @@ channel configuration files, like sip.conf, iax.conf etc.
\item duration: Total time in system, in seconds (integer), from dial to hangup \item duration: Total time in system, in seconds (integer), from dial to hangup
\item billsec: Total time call is up, in seconds (integer), from answer to hangup \item billsec: Total time call is up, in seconds (integer), from answer to hangup
\item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY \item disposition: What happened to the call: ANSWERED, NO ANSWER, BUSY
\item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc, \item amaflags: What flags to use: DOCUMENTATION, BILL, IGNORE etc,
specified on a per channel basis like accountcode. specified on a per channel basis like accountcode.
\item user field: A user-defined field, maximum 255 characters \item user field: A user-defined field, maximum 255 characters
\end{itemize} \end{itemize}
In some cases, uniqueid is appended: In some cases, uniqueid is appended:
\begin{itemize} \begin{itemize}
\item uniqueid: Unique Channel Identifier (32 characters) \item uniqueid: Unique Channel Identifier (32 characters)
This needs to be enabled in the source code at compile time This needs to be enabled in the source code at compile time
\end{itemize} \end{itemize}
@ -55,13 +55,13 @@ have to traverse the middle server(s) in the call).
\section{CDR Variables} \section{CDR Variables}
If the channel has a cdr, that cdr record has its own set of variables which If the channel has a cdr, that cdr record has its own set of variables which
can be accessed just like channel variables. The following builtin variables can be accessed just like channel variables. The following builtin variables
are available. are available.
\begin{verbatim} \begin{verbatim}
${CDR(clid)} Caller ID ${CDR(clid)} Caller ID
${CDR(src)} Source ${CDR(src)} Source
${CDR(dst)} Destination ${CDR(dst)} Destination
${CDR(dcontext)} Destination context ${CDR(dcontext)} Destination context
${CDR(channel)} Channel name ${CDR(channel)} Channel name

136
doc/tex/cdrdriver.tex
View File

@ -14,6 +14,7 @@ Call data records can be stored in many different databases or even CSV text.
\subsection{ODBC using cdr\_odbc} \subsection{ODBC using cdr\_odbc}
Compile, configure, and install the latest unixODBC package: Compile, configure, and install the latest unixODBC package:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
tar -zxvf unixODBC-2.2.9.tar.gz && tar -zxvf unixODBC-2.2.9.tar.gz &&
cd unixODBC-2.2.9 && cd unixODBC-2.2.9 &&
@ -21,8 +22,10 @@ Call data records can be stored in many different databases or even CSV text.
make && make &&
make install make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Compile, configure, and install the latest FreeTDS package: Compile, configure, and install the latest FreeTDS package:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
tar -zxvf freetds-0.62.4.tar.gz && tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 && cd freetds-0.62.4 &&
@ -30,20 +33,23 @@ Call data records can be stored in many different databases or even CSV text.
--with-unixodbc=/usr/lib && --with-unixodbc=/usr/lib &&
make && make install make && make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Compile, or recompile, asterisk so that it will now add support Compile, or recompile, asterisk so that it will now add support
for cdr\_odbc. for cdr\_odbc.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
make clean && ./configure --with-odbc && make clean && ./configure --with-odbc &&
make update && make update &&
make && make &&
make install make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Setup odbc configuration files. These are working examples Setup odbc configuration files. These are working examples
from my system. You will need to modify for your setup. from my system. You will need to modify for your setup.
You are not required to store usernames or passwords here. You are not required to store usernames or passwords here.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
/etc/odbcinst.ini /etc/odbcinst.ini
[FreeTDS] [FreeTDS]
@ -62,19 +68,23 @@ Call data records can be stored in many different databases or even CSV text.
tds_version = 7.0 tds_version = 7.0
language = us_english language = us_english
\end{verbatim} \end{verbatim}
\end{astlisting}
Only install one database connector. Do not confuse asterisk Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
This command will erase the contents of cdr\_tds.conf This command will erase the contents of cdr\_tds.conf
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf [ -f /etc/asterisk/cdr_tds.conf ] > /etc/asterisk/cdr_tds.conf
\end{verbatim} \end{verbatim}
\end{astlisting}
NOTE: unixODBC requires the freeTDS package, but asterisk does NOTE: unixODBC requires the freeTDS package, but asterisk does
not call freeTDS directly. not call freeTDS directly.
Now set up cdr\_odbc configuration files. These are working samples Now set up cdr\_odbc configuration files. These are working samples
from my system. You will need to modify for your setup. Define from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well. your usernames and passwords here, secure file as well.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
/etc/asterisk/cdr_odbc.conf /etc/asterisk/cdr_odbc.conf
[global] [global]
@ -83,9 +93,11 @@ Call data records can be stored in many different databases or even CSV text.
password=voipdbpass password=voipdbpass
loguniqueid=yes loguniqueid=yes
\end{verbatim} \end{verbatim}
\end{astlisting}
And finally, create the 'cdr' table in your mssql database. And finally, create the 'cdr' table in your mssql database.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
CREATE TABLE cdr ( CREATE TABLE cdr (
[calldate] [datetime] NOT NULL , [calldate] [datetime] NOT NULL ,
[clid] [varchar] (80) NOT NULL , [clid] [varchar] (80) NOT NULL ,
[src] [varchar] (80) NOT NULL , [src] [varchar] (80) NOT NULL ,
@ -104,12 +116,14 @@ Call data records can be stored in many different databases or even CSV text.
[userfield] [varchar] (255) NOT NULL [userfield] [varchar] (255) NOT NULL
) )
\end{verbatim} \end{verbatim}
\end{astlisting}
Start asterisk in verbose mode, you should see that asterisk Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every logs a connection to the database and will now record every
call to the database when it's complete. call to the database when it's complete.
\subsection{TDS, using cdr\_tds} \subsection{TDS, using cdr\_tds}
Compile, configure, and install the latest FreeTDS package: Compile, configure, and install the latest FreeTDS package:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
tar -zxvf freetds-0.62.4.tar.gz && tar -zxvf freetds-0.62.4.tar.gz &&
cd freetds-0.62.4 && cd freetds-0.62.4 &&
@ -117,23 +131,29 @@ Call data records can be stored in many different databases or even CSV text.
make && make &&
make install make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Compile, or recompile, asterisk so that it will now add support Compile, or recompile, asterisk so that it will now add support
for cdr\_tds. for cdr\_tds.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
make clean && ./configure --with-tds && make clean && ./configure --with-tds &&
make update && make update &&
make && make &&
make install make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Only install one database connector. Do not confuse asterisk Only install one database connector. Do not confuse asterisk
by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds). by using both ODBC (cdr\_odbc) and FreeTDS (cdr\_tds).
This command will erase the contents of cdr\_odbc.conf This command will erase the contents of cdr\_odbc.conf
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf [ -f /etc/asterisk/cdr_odbc.conf ] > /etc/asterisk/cdr_odbc.conf
\end{verbatim} \end{verbatim}
\end{astlisting}
Setup cdr\_tds configuration files. These are working samples Setup cdr\_tds configuration files. These are working samples
from my system. You will need to modify for your setup. Define from my system. You will need to modify for your setup. Define
your usernames and passwords here, secure file as well. your usernames and passwords here, secure file as well.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
/etc/asterisk/cdr_tds.conf /etc/asterisk/cdr_tds.conf
[global] [global]
@ -144,7 +164,9 @@ Call data records can be stored in many different databases or even CSV text.
password=voipdpass password=voipdpass
charset=BIG5 charset=BIG5
\end{verbatim} \end{verbatim}
\end{astlisting}
And finally, create the 'cdr' table in your mssql database. And finally, create the 'cdr' table in your mssql database.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
CREATE TABLE cdr ( CREATE TABLE cdr (
[accountcode] [varchar] (20) NULL , [accountcode] [varchar] (20) NULL ,
@ -166,6 +188,7 @@ Call data records can be stored in many different databases or even CSV text.
[uniqueid] [varchar] (32) NULL [uniqueid] [varchar] (32) NULL
) )
\end{verbatim} \end{verbatim}
\end{astlisting}
Start asterisk in verbose mode, you should see that asterisk Start asterisk in verbose mode, you should see that asterisk
logs a connection to the database and will now record every logs a connection to the database and will now record every
call to the database when it's complete. call to the database when it's complete.
@ -185,6 +208,7 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
copy the sample cdr\_pgsql.conf file or create your own. copy the sample cdr\_pgsql.conf file or create your own.
Here is a sample: Here is a sample:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
/etc/asterisk/cdr_pgsql.conf /etc/asterisk/cdr_pgsql.conf
; Sample Asterisk config file for CDR logging to PostgresSQL ; Sample Asterisk config file for CDR logging to PostgresSQL
@ -196,8 +220,9 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
user=postgres user=postgres
table=cdr table=cdr
\end{verbatim} \end{verbatim}
\end{astlisting}
Now create a table in postgresql for your cdrs Now create a table in postgresql for your cdrs
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
CREATE TABLE cdr ( CREATE TABLE cdr (
calldate time NOT NULL , calldate time NOT NULL ,
@ -218,6 +243,7 @@ Using MySQL for CDR records is supported by using ODBC and the cdr\_odbc module.
userfield varchar (255) NOT NULL userfield varchar (255) NOT NULL
); );
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{SQLLITE} \section{SQLLITE}
@ -278,46 +304,46 @@ SQLite version 2 is supported in cdr\_sqlite.
authserver localhost authserver localhost
This is the hostname or IP address of the RADIUS server used for This is the hostname or IP address of the RADIUS server used for
authentication. You will have to change this unless the server is authentication. You will have to change this unless the server is
running on the same host as your Asterisk PBX. running on the same host as your Asterisk PBX.
acctserver localhost acctserver localhost
This is the hostname or IP address of the RADIUS server used for This is the hostname or IP address of the RADIUS server used for
accounting. You will have to change this unless the server is running accounting. You will have to change this unless the server is running
on the same host as your Asterisk PBX. on the same host as your Asterisk PBX.
\textbf{File "servers"} \textbf{File "servers"}
RADIUS protocol uses simple access control mechanism based on shared RADIUS protocol uses simple access control mechanism based on shared
secrets that allows RADIUS servers to limit access from RADIUS clients. secrets that allows RADIUS servers to limit access from RADIUS clients.
A RADIUS server is configured with a secret string and only RADIUS A RADIUS server is configured with a secret string and only RADIUS
clients that have the same secret will be accepted. clients that have the same secret will be accepted.
You need to configure a shared secret for each server you have You need to configure a shared secret for each server you have
configured in radiusclient.conf file in the previous step. The shared configured in radiusclient.conf file in the previous step. The shared
secrets are stored in \path{/usr/local/etc/radiusclient-ng/servers} file. secrets are stored in \path{/usr/local/etc/radiusclient-ng/servers} file.
Each line contains hostname of a RADIUS server and shared secret Each line contains hostname of a RADIUS server and shared secret
used in communication with that server. The two values are separated used in communication with that server. The two values are separated
by white spaces. Configure shared secrets for every RADIUS server you by white spaces. Configure shared secrets for every RADIUS server you
are going to use. are going to use.
\textbf{File "dictionary"} \textbf{File "dictionary"}
Asterisk uses some attributes that are not included in the Asterisk uses some attributes that are not included in the
dictionary of radiusclient library, therefore it is necessary to add dictionary of radiusclient library, therefore it is necessary to add
them. A file called dictionary.digium (kept in the contrib dir) them. A file called dictionary.digium (kept in the contrib dir)
was created to list all new attributes used by Asterisk. was created to list all new attributes used by Asterisk.
Add to the end of the main dictionary file Add to the end of the main dictionary file
\path{/usr/local/etc/radiusclient-ng/dictionary} the line: \path{/usr/local/etc/radiusclient-ng/dictionary} the line:
\$INCLUDE /path/to/dictionary.digium \$INCLUDE /path/to/dictionary.digium
\subsubsection{Install FreeRADIUS Server (Version 1.1.1)} \subsubsection{Install FreeRADIUS Server (Version 1.1.1)}
Download sources tarball from: Download sources tarball from:
\url{http://freeradius.org/} \url{http://freeradius.org/}
@ -332,8 +358,8 @@ SQLite version 2 is supported in cdr\_sqlite.
root@localhost"/usr/local/src/freeradius-1.1.1# make install root@localhost"/usr/local/src/freeradius-1.1.1# make install
\end{verbatim} \end{verbatim}
All the configuration files of FreeRADIUS server will be in All the configuration files of FreeRADIUS server will be in
/usr/local/etc/raddb directory. /usr/local/etc/raddb directory.
\subsubsection{Configuration of the FreeRADIUS Server} \subsubsection{Configuration of the FreeRADIUS Server}
@ -343,9 +369,9 @@ SQLite version 2 is supported in cdr\_sqlite.
File "clients.conf" File "clients.conf"
File \path{/usr/local/etc/raddb/clients.conf} contains description of File \path{/usr/local/etc/raddb/clients.conf} contains description of
RADIUS clients that are allowed to use the server. For each of the RADIUS clients that are allowed to use the server. For each of the
clients you need to specify its hostname or IP address and also a clients you need to specify its hostname or IP address and also a
shared secret. The shared secret must be the same string you configured shared secret. The shared secret must be the same string you configured
in radiusclient library. in radiusclient library.
@ -357,29 +383,29 @@ SQLite version 2 is supported in cdr\_sqlite.
} }
\end{verbatim} \end{verbatim}
This fragment allows access from RADIUS clients on "myhost" if they use This fragment allows access from RADIUS clients on "myhost" if they use
"mysecret" as the shared secret. "mysecret" as the shared secret.
The file already contains an entry for localhost (127.0.0.1), so if you The file already contains an entry for localhost (127.0.0.1), so if you
are running the RADIUS server on the same host as your Asterisk server, are running the RADIUS server on the same host as your Asterisk server,
then modify the existing entry instead, replacing the default password. then modify the existing entry instead, replacing the default password.
File "dictionary" File "dictionary"
Note: as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS. Note: as of version 1.1.2, the dictionary.digium file ships with FreeRADIUS.
The following procedure brings the dictionary.digium file to previous versions The following procedure brings the dictionary.digium file to previous versions
of FreeRADIUS. of FreeRADIUS.
File \path{/usr/local/etc/raddb/dictionary} contains the dictionary of File \path{/usr/local/etc/raddb/dictionary} contains the dictionary of
FreeRADIUS server. You have to add the same dictionary file FreeRADIUS server. You have to add the same dictionary file
(dictionary.digium), which you added to the dictionary of radiusclient-ng (dictionary.digium), which you added to the dictionary of radiusclient-ng
library. You can include it into the main file, adding the following line at the library. You can include it into the main file, adding the following line at the
end of file \path{/usr/local/etc/raddb/dictionary}: end of file \path{/usr/local/etc/raddb/dictionary}:
\$INCLUDE /path/to/dictionary.digium \$INCLUDE /path/to/dictionary.digium
That will include the same new attribute definitions that are used That will include the same new attribute definitions that are used
in radiusclient-ng library so the client and server will understand each in radiusclient-ng library so the client and server will understand each
other. other.
\subsubsection{Asterisk Accounting Configuration} \subsubsection{Asterisk Accounting Configuration}
@ -389,17 +415,17 @@ SQLite version 2 is supported in cdr\_sqlite.
The module will be compiled as long as the radiusclient-ng The module will be compiled as long as the radiusclient-ng
library has been detected on your system. library has been detected on your system.
By default FreeRADIUS server will log all accounting requests into By default FreeRADIUS server will log all accounting requests into
\path{/usr/local/var/log/radius/radacct} directory in form of plain text files. \path{/usr/local/var/log/radius/radacct} directory in form of plain text files.
The server will create one file for each hostname in the directory. The The server will create one file for each hostname in the directory. The
following example shows how the log files look like. following example shows how the log files look like.
Asterisk now generates Call Detail Records. See \path{/include/asterisk/cdr.h} Asterisk now generates Call Detail Records. See \path{/include/asterisk/cdr.h}
for all the fields which are recorded. By default, records in comma for all the fields which are recorded. By default, records in comma
separated values will be created in \path{/var/log/asterisk/cdr-csv}. separated values will be created in \path{/var/log/asterisk/cdr-csv}.
The configuration file for cdr\_radius.so module is \path{/etc/asterisk/cdr.conf} The configuration file for cdr\_radius.so module is \path{/etc/asterisk/cdr.conf}
This is where you can set CDR related parameters as well as the path to This is where you can set CDR related parameters as well as the path to
the radiusclient-ng library configuration file. the radiusclient-ng library configuration file.
@ -413,20 +439,20 @@ SQLite version 2 is supported in cdr\_sqlite.
"Asterisk-Clid", "Asterisk-Clid",
"Asterisk-Chan", The channel "Asterisk-Chan", The channel
"Asterisk-Dst-Chan", (if applicable) "Asterisk-Dst-Chan", (if applicable)
"Asterisk-Last-App", Last application run on the channel "Asterisk-Last-App", Last application run on the channel
"Asterisk-Last-Data", Argument to the last channel "Asterisk-Last-Data", Argument to the last channel
"Asterisk-Start-Time", "Asterisk-Start-Time",
"Asterisk-Answer-Time", "Asterisk-Answer-Time",
"Asterisk-End-Time", "Asterisk-End-Time",
"Asterisk-Duration", Duration is the whole length that the entire "Asterisk-Duration", Duration is the whole length that the entire
call lasted. ie. call rx'd to hangup call lasted. ie. call rx'd to hangup
"end time" minus "start time" "end time" minus "start time"
"Asterisk-Bill-Sec", The duration that a call was up after other "Asterisk-Bill-Sec", The duration that a call was up after other
end answered which will be <= to duration end answered which will be <= to duration
"end time" minus "answer time" "end time" minus "answer time"
"Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY "Asterisk-Disposition", ANSWERED, NO ANSWER, BUSY
"Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on "Asterisk-AMA-Flags", DOCUMENTATION, BILL, IGNORE etc, specified on
a per channel basis like accountcode. a per channel basis like accountcode.
"Asterisk-Unique-ID", Unique call identifier "Asterisk-Unique-ID", Unique call identifier
"Asterisk-User-Field" User field set via SetCDRUserField "Asterisk-User-Field" User field set via SetCDRUserField
\end{verbatim} \end{verbatim}

120
doc/tex/channelvariables.tex
View File

@ -13,9 +13,11 @@ by various modules in Asterisk. These standard variables are
listed at the end of this document. listed at the end of this document.
\section{Parameter Quoting} \section{Parameter Quoting}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => s,5,BackGround,blabla exten => s,5,BackGround,blabla
\end{verbatim} \end{verbatim}
\end{astlisting}
The parameter (blabla) can be quoted ("blabla"). In this case, a The parameter (blabla) can be quoted ("blabla"). In this case, a
comma does not terminate the field. However, the double quotes comma does not terminate the field. However, the double quotes
will be passed down to the Background command, in this example. will be passed down to the Background command, in this example.
@ -36,29 +38,35 @@ Parameter strings can include variables. Variable names are arbitrary strings.
They are stored in the respective channel structure. They are stored in the respective channel structure.
To set a variable to a particular value, do: To set a variable to a particular value, do:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,2,Set(varname=value) exten => 1,2,Set(varname=value)
\end{verbatim} \end{verbatim}
You can substitute the value of a variable everywhere using \${variablename}. \end{astlisting}
You can substitute the value of a variable everywhere using \$\{variablename\}.
For example, to stringwise append \$lala to \$blabla and store result in \$koko, For example, to stringwise append \$lala to \$blabla and store result in \$koko,
do: do:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,2,Set(koko=${blabla}${lala}) exten => 1,2,Set(koko=${blabla}${lala})
\end{verbatim} \end{verbatim}
\end{astlisting}
There are two reference modes - reference by value and reference by name. There are two reference modes - reference by value and reference by name.
To refer to a variable with its name (as an argument to a function that To refer to a variable with its name (as an argument to a function that
requires a variable), just write the name. To refer to the variable's value, requires a variable), just write the name. To refer to the variable's value,
enclose it inside \${}. For example, Set takes as the first argument enclose it inside \$\{\}. For example, Set takes as the first argument
(before the =) a variable name, so: (before the =) a variable name, so:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,2,Set(koko=lala) exten => 1,2,Set(koko=lala)
exten => 1,3,Set(${koko}=blabla) exten => 1,3,Set(${koko}=blabla)
\end{verbatim} \end{verbatim}
\end{astlisting}
stores to the variable "koko" the value "lala" and to variable "lala" the stores to the variable "koko" the value "lala" and to variable "lala" the
value "blabla". value "blabla".
In fact, everything contained \${here} is just replaced with the value of In fact, everything contained \$\{here\} is just replaced with the value of
the variable "here". the variable "here".
\section{Variable Inheritance} \section{Variable Inheritance}
@ -76,30 +84,33 @@ version of the variable removes any other version of the variable,
regardless of prefix. regardless of prefix.
\subsection{Example} \subsection{Example}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
Set(__FOO=bar) ; Sets an inherited version of "FOO" variable Set(__FOO=bar) ; Sets an inherited version of "FOO" variable
Set(FOO=bar) ; Removes the inherited version and sets a local Set(FOO=bar) ; Removes the inherited version and sets a local
; variable. ; variable.
However,
NoOp(${__FOO}) is identical to NoOp(${FOO})
\end{verbatim} \end{verbatim}
\end{astlisting}
However, NoOp(\$\{\_\_FOO\}) is identical to NoOp(\$\{FOO\})
\section{Selecting Characters from Variables} \section{Selecting Characters from Variables}
The format for selecting characters from a variable can be expressed as: The format for selecting characters from a variable can be expressed as:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
${variable_name[:offset[:length]]} ${variable_name[:offset[:length]]}
\end{verbatim} \end{verbatim}
\end{astlisting}
If you want to select the first N characters from the string assigned If you want to select the first N characters from the string assigned
to a variable, simply append a colon and the number of characters to to a variable, simply append a colon and the number of characters to
skip from the beginning of the string to the variable name. skip from the beginning of the string to the variable name.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
; Remove the first character of extension, save in "number" variable ; Remove the first character of extension, save in "number" variable
exten => _9X.,1,Set(number=${EXTEN:1}) exten => _9X.,1,Set(number=${EXTEN:1})
\end{verbatim} \end{verbatim}
\end{astlisting}
Assuming we've dialed 918005551234, the value saved to the 'number' variable Assuming we've dialed 918005551234, the value saved to the 'number' variable
would be 18005551234. This is useful in situations when we require users to would be 18005551234. This is useful in situations when we require users to
dial a number to access an outside line, but do not wish to pass the first dial a number to access an outside line, but do not wish to pass the first
@ -109,33 +120,41 @@ If you use a negative offset number, Asterisk starts counting from the end
of the string and then selects everything after the new position. The following of the string and then selects everything after the new position. The following
example will save the numbers 1234 to the 'number' variable, still assuming example will save the numbers 1234 to the 'number' variable, still assuming
we've dialed 918005551234. we've dialed 918005551234.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
; Remove everything before the last four digits of the dialed string ; Remove everything before the last four digits of the dialed string
exten => _9X.,1,Set(number=${EXTEN:-4}) exten => _9X.,1,Set(number=${EXTEN:-4})
\end{verbatim} \end{verbatim}
\end{astlisting}
We can also limit the number of characters from our offset position that we We can also limit the number of characters from our offset position that we
wish to use. This is done by appending a second colon and length value to the wish to use. This is done by appending a second colon and length value to the
variable name. The following example will save the numbers 555 to the 'number' variable name. The following example will save the numbers 555 to the 'number'
variable. variable.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
; Only save the middle numbers 555 from the string 918005551234 ; Only save the middle numbers 555 from the string 918005551234
exten => _9X.,1,Set(number=${EXTEN:5:3}) exten => _9X.,1,Set(number=${EXTEN:5:3})
\end{verbatim} \end{verbatim}
\end{astlisting}
The length value can also be used in conjunction with a negative offset. This The length value can also be used in conjunction with a negative offset. This
may be useful if the length of the string is unknown, but the trailing digits may be useful if the length of the string is unknown, but the trailing digits
are. The following example will save the numbers 555 to the 'number' variable, are. The following example will save the numbers 555 to the 'number' variable,
even if the string starts with more characters than expected (unlike the even if the string starts with more characters than expected (unlike the
previous example). previous example).
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
; Save the numbers 555 to the 'number' variable ; Save the numbers 555 to the 'number' variable
exten => _9X.,1,Set(number=${EXTEN:-7:3}) exten => _9X.,1,Set(number=${EXTEN:-7:3})
\end{verbatim} \end{verbatim}
\end{astlisting}
If a negative length value is entered, Asterisk will remove that many characters If a negative length value is entered, Asterisk will remove that many characters
from the end of the string. from the end of the string.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
; Set pin to everything but the trailing #. ; Set pin to everything but the trailing #.
exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) exten => _XXXX#,1,Set(pin=${EXTEN:0:-1})
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Expressions} \section{Expressions}
@ -146,16 +165,20 @@ considered as an expression and it is evaluated. Evaluation works similar to
evaluation. evaluation.
For example, after the sequence: For example, after the sequence:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,1,Set(lala=$[1 + 2]) exten => 1,1,Set(lala=$[1 + 2])
exten => 1,2,Set(koko=$[2 * ${lala}]) exten => 1,2,Set(koko=$[2 * ${lala}])
\end{verbatim} \end{verbatim}
\end{astlisting}
the value of variable koko is "6". the value of variable koko is "6".
and, further: and, further:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,1,Set,(lala=$[ 1 + 2 ]); exten => 1,1,Set,(lala=$[ 1 + 2 ]);
\end{verbatim} \end{verbatim}
\end{astlisting}
will parse as intended. Extra spaces are ignored. will parse as intended. Extra spaces are ignored.
@ -169,9 +192,11 @@ The double quotes will be counted as part of that lexical token.
As an example: As an example:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7)
\end{verbatim} \end{verbatim}
\end{astlisting}
The variable CALLERID(name) could evaluate to "DELOREAN MOTORS" (with a space) The variable CALLERID(name) could evaluate to "DELOREAN MOTORS" (with a space)
but the above will evaluate to: but the above will evaluate to:
@ -195,7 +220,7 @@ evaluate this expression, because it does not match its grammar.
\subsection{Operators} \subsection{Operators}
Operators are listed below in order of increasing precedence. Operators Operators are listed below in order of increasing precedence. Operators
with equal precedence are grouped within { } symbols. with equal precedence are grouped within \{ \} symbols.
\begin{itemize} \begin{itemize}
\item \verb!expr1 | expr2! \item \verb!expr1 | expr2!
@ -337,8 +362,7 @@ though! -- you still need to wrap variable names in curly braces!
\item ROUND(x) rounds x to the nearest integer, but round halfway cases away from zero. \item ROUND(x) rounds x to the nearest integer, but round halfway cases away from zero.
\item RINT(x) rounds x to the nearest integer, rounding halfway cases to the nearest even integer. \item RINT(x) rounds x to the nearest integer, rounding halfway cases to the nearest even integer.
\item TRUNC(x) rounds x to the nearest integer not larger in absolute value. \item TRUNC(x) rounds x to the nearest integer not larger in absolute value.
\item REMAINDER(x,y) computes the remainder of dividing x by y. The return value is x - n*y, where n is the value x/y, rounded to the nearest integer. \item REMAINDER(x,y) computes the remainder of dividing x by y. The return value is x - n*y, where n is the value x/y, rounded to the nearest integer. If this quotient is 1/2, it is rounded to the nearest even number.
If this quotient is 1/2, it is rounded to the nearest even number.
\item EXP(x) returns e to the x power. \item EXP(x) returns e to the x power.
\item EXP2(x) returns 2 to the x power. \item EXP2(x) returns 2 to the x power.
\item LOG(x) returns the natural logarithm of x. \item LOG(x) returns the natural logarithm of x.
@ -436,7 +460,7 @@ TRUNC(-3.5)
Of course, all of the above examples use constants, but would work the Of course, all of the above examples use constants, but would work the
same if any of the numeric or string constants were replaced with a same if any of the numeric or string constants were replaced with a
variable reference \${CALLERID(num)}, for instance. variable reference \$\{CALLERID(num)\}, for instance.
\subsection{Numbers Vs. Strings} \subsection{Numbers Vs. Strings}
@ -450,10 +474,11 @@ case.
\subsection{Conditionals} \subsection{Conditionals}
There is one conditional application - the conditional goto : There is one conditional application - the conditional goto :
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,2,GotoIf(condition?label1:label2) exten => 1,2,GotoIf(condition?label1:label2)
\end{verbatim} \end{verbatim}
\end{astlisting}
If condition is true go to label1, else go to label2. Labels are interpreted If condition is true go to label1, else go to label2. Labels are interpreted
exactly as in the normal goto command. exactly as in the normal goto command.
@ -463,18 +488,21 @@ is considered to be false, if it's anything else, the condition is true.
This is designed to be used together with the expression syntax described This is designed to be used together with the expression syntax described
above, eg : above, eg :
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,2,GotoIf($[${CALLERID(all)} = 123456]?2,1:3,1) exten => 1,2,GotoIf($[${CALLERID(all)} = 123456]?2,1:3,1)
\end{verbatim} \end{verbatim}
\end{astlisting}
Example of use : Example of use :
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => s,2,Set(vara=1) exten => s,2,Set(vara=1)
exten => s,3,Set(varb=$[${vara} + 2]) exten => s,3,Set(varb=$[${vara} + 2])
exten => s,4,Set(varc=$[${varb} * 2]) exten => s,4,Set(varc=$[${varb} * 2])
exten => s,5,GotoIf($[${varc} = 6]?99,1:s,6) exten => s,5,GotoIf($[${varc} = 6]?99,1:s,6)
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Parse Errors} \subsection{Parse Errors}
@ -488,7 +516,7 @@ exten => s,6,GotoIf($[ "${CALLERID(num)}" = "3071234567" & & "${CALLERID(name)
\end{verbatim} \end{verbatim}
\end{astlisting} \end{astlisting}
You may see an error in /var/log/asterisk/messages like this: You may see an error in \path{/var/log/asterisk/messages} like this:
\begin{astlisting} \begin{astlisting}
\begin{verbatim} \begin{verbatim}
Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input: Jul 15 21:27:49 WARNING[1251240752]: ast_yyerror(): syntax error: parse error, unexpected TOK_AND, expecting TOK_MINUS or TOK_LP or TOKEN; Input:
@ -508,11 +536,13 @@ marked with the "\^" character.
\subsection{NULL Strings} \subsection{NULL Strings}
Testing to see if a string is null can be done in one of two different ways: Testing to see if a string is null can be done in one of two different ways:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)
or
exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
\end{verbatim} \end{verbatim}
\end{astlisting}
The second example above is the way suggested by the WIKI. It will The second example above is the way suggested by the WIKI. It will
work as long as there are no spaces in the evaluated value. work as long as there are no spaces in the evaluated value.
@ -578,10 +608,10 @@ of possible concern with "legacy" extension.conf files:
and the average regex expression is full of operators that and the average regex expression is full of operators that
the scanner will recognize as expression operators. Thus, unless the scanner will recognize as expression operators. Thus, unless
the pattern is wrapped in double quotes, there will be trouble. the pattern is wrapped in double quotes, there will be trouble.
For instance, \${VAR1} : (Who|What*)+ For instance, \$\{VAR1\} : (Who$|$What*)+
may have have worked before, but unless you wrap the pattern may have have worked before, but unless you wrap the pattern
in double quotes now, look out for trouble! This is better: in double quotes now, look out for trouble! This is better:
"\${VAR1}" : "(Who|What*)+" "\$\{VAR1\}" : "(Who$|$What*)+"
and should work as previous. and should work as previous.
\item Variables and Double Quotes \item Variables and Double Quotes
@ -602,7 +632,7 @@ of possible concern with "legacy" extension.conf files:
match anywhere in the string. The only diff with the ':' is that match anywhere in the string. The only diff with the ':' is that
match doesn't have to be anchored to the beginning of the string. match doesn't have to be anchored to the beginning of the string.
\item Added the conditional operator 'expr1 ? true\_expr :: false\_expr' \item Added the conditional operator 'expr1 ? true\_expr : false\_expr'
First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr' First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr'
is returned as the result. See above for details. is returned as the result. See above for details.
@ -615,23 +645,29 @@ There are two utilities you can build to help debug the \$[ ] in
your extensions.conf file. your extensions.conf file.
The first, and most simplistic, is to issue the command: The first, and most simplistic, is to issue the command:
\begin{astlisting}
\begin{verbatim}
make testexpr2 make testexpr2
\end{verbatim}
\end{astlisting}
in the top level asterisk source directory. This will build a small in the top level asterisk source directory. This will build a small
executable, that is able to take the first command line argument, and executable, that is able to take the first command line argument, and
run it thru the expression parser. No variable substitutions will be run it thru the expression parser. No variable substitutions will be
performed. It might be safest to wrap the expression in single performed. It might be safest to wrap the expression in single
quotes... quotes...
\begin{astlisting}
\begin{verbatim}
testexpr2 '2*2+2/2' testexpr2 '2*2+2/2'
\end{verbatim}
\end{astlisting}
is an example. is an example.
And, in the utils directory, you can say: And, in the utils directory, you can say:
\begin{astlisting}
make check\_expr \begin{verbatim}
make check_expr
\end{verbatim}
\end{astlisting}
and a small program will be built, that will check the file mentioned and a small program will be built, that will check the file mentioned
in the first command line argument, for any expressions that might be in the first command line argument, for any expressions that might be
have problems when you move to flex-2.5.31. It was originally have problems when you move to flex-2.5.31. It was originally
@ -645,33 +681,41 @@ are any parse errors, they will be reported in the log file. You can
use check\_expr to do a quick sanity check of the expressions in your use check\_expr to do a quick sanity check of the expressions in your
extensions.conf file, to see if they pass a crude syntax check. extensions.conf file, to see if they pass a crude syntax check.
The "simple-minded" variable substitution replaces \${varname} variable The "simple-minded" variable substitution replaces \$\{varname\} variable
references with '555'. You can override the 555 for variable values, references with '555'. You can override the 555 for variable values,
by entering in var=val arguments after the filename on the command by entering in var=val arguments after the filename on the command
line. So... line. So...
\begin{astlisting}
check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121 \begin{verbatim}
check_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121
will substitute any \${CALLERIDNUM} variable references with \end{verbatim}
3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and \end{astlisting}
any \${EXTEN} references with '121'. If there is any fancy stuff will substitute any \$\{CALLERID(num)\} variable references with
going on in the reference, like \${EXTEN:2}, then the override will 3075551212, any \$\{DIALSTATUS\} variable references with 'TORTURE', and
not work. Everything in the \${...} has to match. So, to substitute any \$\{EXTEN\} references with '121'. If there is any fancy stuff
\${EXTEN:2} references, you'd best say: going on in the reference, like \$\{EXTEN:2\}, then the override will
not work. Everything in the \$\{...\} has to match. So, to substitute
check\_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN:2=121 \$\{EXTEN:2\} references, you'd best say:
\begin{astlisting}
\begin{verbatim}
check_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
\end{verbatim}
\end{astlisting}
on stdout, you will see something like: on stdout, you will see something like:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416 OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416
\end{verbatim} \end{verbatim}
\end{astlisting}
In the expr2\_log file that is generated, you will see: In the expr2\_log file that is generated, you will see:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1
\end{verbatim} \end{verbatim}
\end{astlisting}
check\_expr is a very simplistic algorithm, and it is far from being check\_expr is a very simplistic algorithm, and it is far from being
guaranteed to work in all cases, but it is hoped that it will be guaranteed to work in all cases, but it is hoped that it will be

37
doc/tex/cliprompt.tex
View File

@ -6,25 +6,24 @@ you set from the Unix shell before starting Asterisk
You may include the following variables, that will be replaced by You may include the following variables, that will be replaced by
the current value by Asterisk: the current value by Asterisk:
\begin{verbatim} \begin{itemize}
%d Date (year-month-date) \item \%d - Date (year-month-date)
%s Asterisk system name (from asterisk.conf) \item \%s - Asterisk system name (from asterisk.conf)
%h Full hostname \item \%h - Full hostname
%H Short hostname \item \%H - Short hostname
%t Time \item \%t - Time
%% Percent sign \item \%\% - Percent sign
%# '#' if Asterisk is run in console mode, '>' if running as remote console \item \%\# - '\#' if Asterisk is run in console mode, '$>$' if running as remote console
%Cn[;n] Change terminal foreground (and optional background) color to specified \item \%Cn[;n] - Change terminal foreground (and optional background) color to specified
\end{verbatim} A full list of colors may be found in \path{include/asterisk/term.h}
\end{itemize}
A full list of colors may be found in \path{include/asterisk/term.h}
On Linux systems, you may also use: On Linux systems, you may also use:
\begin{verbatim} \begin{itemize}
%l1 Load average over past minute \item \%l1 - Load average over past minute
%l2 Load average over past 5 minutes \item \%l2 - Load average over past 5 minutes
%l3 Load average over past 15 minutes \item \%l3 - Load average over past 15 minutes
%l4 Process fraction (processes running / total processes) \item \%l4 - Process fraction (processes running / total processes)
%l5 The most recently allocated pid \item \%l5 - The most recently allocated pid
\end{verbatim} \end{itemize}

51
doc/tex/configuration.tex
View File

@ -7,20 +7,23 @@ templates in configuration files, and use these as templates when we
configure phones, voicemail accounts and queues. configure phones, voicemail accounts and queues.
These changes are general to the configuration parser, and works in These changes are general to the configuration parser, and works in
all configuration files. all configuration files.
\subsubsection{General syntax} \subsubsection{General syntax}
Asterisk configuration files are defined as follows: Asterisk configuration files are defined as follows:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section] [section]
label = value label = value
label2 = value label2 = value
\end{verbatim} \end{verbatim}
\end{astlisting}
In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
is a bit different. In these files the syntax is as follows: is a bit different. In these files the syntax is as follows:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section] [section]
label1 = value1 label1 = value1
@ -31,17 +34,20 @@ is a bit different. In these files the syntax is as follows:
label2 = value4 label2 = value4
object2 => name2 object2 => name2
\end{verbatim} \end{verbatim}
\end{astlisting}
In this syntax, we create objects with the settings defined above the object In this syntax, we create objects with the settings defined above the object
creation. Note that settings are inherited from the top, so in the example creation. Note that settings are inherited from the top, so in the example
above object2 has inherited the setting for "label1" from the first object. above object2 has inherited the setting for "label1" from the first object.
For template configurations, the syntax for defining a section is changed For template configurations, the syntax for defining a section is changed
to: to:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section](options) [section](options)
label = value label = value
\end{verbatim} \end{verbatim}
\end{astlisting}
The options field is used to define templates, refer to templates and hide The options field is used to define templates, refer to templates and hide
templates. Any object can be used as a template. templates. Any object can be used as a template.
@ -53,52 +59,61 @@ No whitespace is allowed between the closing "]" and the parenthesis "(".
All lines that starts with semi-colon ";" is treated as comments All lines that starts with semi-colon ";" is treated as comments
and is not parsed. and is not parsed.
The ";--" is a marker for a multi-line comment. Everything after The "\verb!;--!" is a marker for a multi-line comment. Everything after
that marker will be treated as a comment until the end-marker "--;" that marker will be treated as a comment until the end-marker "\verb!--;!"
is found. Parsing begins directly after the end-marker. is found. Parsing begins directly after the end-marker.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
;This is a comment ;This is a comment
label = value label = value
;-- This is ;-- This is
a comment --; a comment --;
;-- Comment --; exten=> 1000,1,dial(SIP/lisa) ;-- Comment --; exten=> 1000,1,dial(SIP/lisa)
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsubsection{Including other files} \subsubsection{Including other files}
In all of the configuration files, you may include the content of another In all of the configuration files, you may include the content of another
file with the \#include statement. The content of the other file will be file with the \#include statement. The content of the other file will be
included at the row that the \#include statement occurred. included at the row that the \#include statement occurred.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
#include myusers.conf #include myusers.conf
\end{verbatim} \end{verbatim}
\end{astlisting}
You may also include the output of a program with the \#exec directive, You may also include the output of a program with the \#exec directive,
if you enable it in asterisk.conf if you enable it in asterisk.conf
In asterisk.conf, add the execincludes = yes statement in the options In asterisk.conf, add the execincludes = yes statement in the options
section: section:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[options] [options]
execincludes=yes execincludes=yes
\end{verbatim} \end{verbatim}
\end{astlisting}
The exec directive is used like this: The exec directive is used like this:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
#exec /usr/local/bin/myasteriskconfigurator.sh #exec /usr/local/bin/myasteriskconfigurator.sh
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsubsection{Adding to an existing section} \subsubsection{Adding to an existing section}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section] [section]
label = value label = value
[section](+) [section](+)
label2 = value2 label2 = value2
\end{verbatim} \end{verbatim}
\end{astlisting}
In this case, the plus sign indicates that the second section (with the In this case, the plus sign indicates that the second section (with the
same name) is an addition to the first section. The second section can same name) is an addition to the first section. The second section can
@ -107,29 +122,34 @@ name referred to before the plus is missing, the configuration will fail
to load. to load.
\subsubsection{Defining a template-only section} \subsubsection{Defining a template-only section}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section](!) [section](!)
label = value label = value
\end{verbatim} \end{verbatim}
\end{astlisting}
The exclamation mark indicates to the config parser that this is a only The exclamation mark indicates to the config parser that this is a only
a template and should not itself be used by the Asterisk module for a template and should not itself be used by the Asterisk module for
configuration. The section can be inherited by other sections (see configuration. The section can be inherited by other sections (see
section "Using templates" below) but is not used by itself. section "Using templates" below) but is not used by itself.
\subsubsection{Using templates (or other configuration sections)} \subsubsection{Using templates (or other configuration sections)}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[section](name[,name]) [section](name[,name])
label = value label = value
\end{verbatim} \end{verbatim}
\end{astlisting}
The name within the parenthesis refers to other sections, either The name within the parenthesis refers to other sections, either
templates or standard sections. The referred sections are included templates or standard sections. The referred sections are included
before the configuration engine parses the local settings within the before the configuration engine parses the local settings within the
section as though their entire contents (and anything they were section as though their entire contents (and anything they were
previously based upon) were included in the new section. For example previously based upon) were included in the new section. For example
consider the following: consider the following:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[foo] [foo]
permit=192.168.0.2 permit=192.168.0.2
@ -145,10 +165,12 @@ deny=192.168.1.1
permit=192.168.3.1 permit=192.168.3.1
host=bnm host=bnm
\end{verbatim} \end{verbatim}
\end{astlisting}
The [baz] section will be processed as though it had been written in the The [baz] section will be processed as though it had been written in the
following way: following way:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[baz] [baz]
permit=192.168.0.2 permit=192.168.0.2
@ -160,11 +182,13 @@ deny=192.168.1.1
permit=192.168.3.1 permit=192.168.3.1
host=bnm host=bnm
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsubsection{Additional Examples} \subsubsection{Additional Examples}
(in top-level sip.conf) (in top-level sip.conf)
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[defaults](!) [defaults](!)
type=friend type=friend
@ -176,9 +200,11 @@ allow=alaw
#include accounts/*/sip.conf #include accounts/*/sip.conf
\end{verbatim} \end{verbatim}
\end{astlisting}
(in accounts/customer1/sip.conf) (in \path{accounts/customer1/sip.conf})
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[def-customer1](!,defaults) [def-customer1](!,defaults)
secret=this_is_not_secret secret=this_is_not_secret
@ -192,6 +218,7 @@ mailbox=phone1@customer1
[phone2](def-customer1) [phone2](def-customer1)
mailbox=phone2@customer1 mailbox=phone2@customer1
\end{verbatim} \end{verbatim}
\end{astlisting}
This example defines two phones - phone1 and phone2 with settings This example defines two phones - phone1 and phone2 with settings
inherited from "def-customer1". The "def-customer1" is a template that inherited from "def-customer1". The "def-customer1" is a template that

8
doc/tex/dundi.tex
View File

@ -27,15 +27,15 @@ For more information visit \url{http://www.dundi.com}
The DUNDIQUERY and DUNDIRESULT dialplan functions will let you initiate The DUNDIQUERY and DUNDIRESULT dialplan functions will let you initiate
a DUNDi query from the dialplan, see how many results there are, and access a DUNDi query from the dialplan, see how many results there are, and access
each one. Here is some example usage: each one. Here is some example usage:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 1,1,Set(ID=${DUNDIQUERY(1,dundi_test,b)}) exten => 1,1,Set(ID=${DUNDIQUERY(1,dundi_test,b)})
exten => 1,n,Set(NUM=${DUNDIRESULT(${ID},getnum)}) exten => 1,n,Set(NUM=${DUNDIRESULT(${ID},getnum)})
exten => 1,n,NoOp(There are ${NUM} results) exten => 1,n,NoOp(There are ${NUM} results)
exten => 1,n,Set(X=1) exten => 1,n,Set(X=1)
exten => 1,n,While($[${X} <= ${NUM}]) exten => 1,n,While($[${X} <= ${NUM}])
exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID},${X})}) exten => 1,n,NoOp(Result ${X} is ${DUNDIRESULT(${ID},${X})})
exten => 1,n,Set(X=$[${X} + 1]) exten => 1,n,Set(X=$[${X} + 1])
exten => 1,n,EndWhile exten => 1,n,EndWhile
\end{verbatim} \end{verbatim}
\end{astlisting}

6
doc/tex/extensions.tex
View File

@ -22,11 +22,11 @@ some modules which use explicitly GOTO's.
Extensions frequently have data they pass to the executing application Extensions frequently have data they pass to the executing application
(most frequently a string). You can see the available dialplan applications (most frequently a string). You can see the available dialplan applications
by entering the "show applications" command in the CLI. by entering the "core show applications" command in the CLI.
In this version of Asterisk, dialplan functions are added. These can In this version of Asterisk, dialplan functions are added. These can
be used as arguments to any application. For a list of the installed be used as arguments to any application. For a list of the installed
functions in your Asterisk, use the "show functions" command. functions in your Asterisk, use the "core show functions" command.
\subsubsection{Example dialplan} \subsubsection{Example dialplan}
@ -63,7 +63,7 @@ There are some extensions with important meanings:
\item T \item T
\begin{itemize} \begin{itemize}
\item This is the extension that is executed when the 'absolute' \item This is the extension that is executed when the 'absolute'
timeout is reached. See "show function TIMEOUT" for more timeout is reached. See "core show function TIMEOUT" for more
information on setting timeouts. information on setting timeouts.
\end{itemize} \end{itemize}
\item e \item e

51
doc/tex/imapstorage.tex
View File

@ -11,7 +11,7 @@ additional voicemail functionality, including:
mailbox automatically. mailbox automatically.
\item Accessing a voicemail recording email message will turn off the message \item Accessing a voicemail recording email message will turn off the message
waiting indicator (MWI) on the user's phone. waiting indicator (MWI) on the user's phone.
\item Deleting a voicemail recording email will also turn off the message \item Deleting a voicemail recording email will also turn off the message
waiting indicator, and delete the message from the voicemail system. waiting indicator, and delete the message from the voicemail system.
\end{itemize} \end{itemize}
@ -38,13 +38,16 @@ is outside the scope of this document.
Building the c-client library is fairly straightforward; for example, on a Building the c-client library is fairly straightforward; for example, on a
Debian system there are two possibilities: Debian system there are two possibilities:
\begin{verbatim} \begin{enumerate}
1) if you will not be using SSL to connect to the IMAP server: \item If you will not be using SSL to connect to the IMAP server:
$ make slx SSLTYPE=none \begin{verbatim}
$ make slx SSLTYPE=none!
2) if you will be using SSL to connect to the IMAP server: \end{verbatim}
\item If you will be using SSL to connect to the IMAP server:
\begin{verbatim}
$ make slx EXTRACFLAGS="-I/usr/include/openssl" $ make slx EXTRACFLAGS="-I/usr/include/openssl"
\end{verbatim} \end{verbatim}
\end{enumerate}
Once this completes you can proceed with the Asterisk build; there is no Once this completes you can proceed with the Asterisk build; there is no
need to run 'make install'. need to run 'make install'.
@ -66,7 +69,7 @@ normally.
\subsection{Modify voicemail.conf} \subsection{Modify voicemail.conf}
The following directives have been added to voicemail.conf: The following directives have been added to voicemail.conf:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
imapserver=<name or IP address of IMAP mail server> imapserver=<name or IP address of IMAP mail server>
imapport=<IMAP port, defaults to 143> imapport=<IMAP port, defaults to 143>
@ -75,27 +78,29 @@ expungeonhangup=<yes or no>
authuser=<username> authuser=<username>
authpassword=<password> authpassword=<password>
\end{verbatim} \end{verbatim}
\end{astlisting}
The "expungeonhangup" flag is used to determine if the voicemail system should The "expungeonhangup" flag is used to determine if the voicemail system should
expunge all messages marked for deletion when the user hangs up the phone. expunge all messages marked for deletion when the user hangs up the phone.
Each mailbox definition should also have imapuser=$<$imap username$>$. Each mailbox definition should also have imapuser=$<$imap username$>$.
For example: For example:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
\end{verbatim} \end{verbatim}
\end{astlisting}
The directives "authuser" and "authpassword" are not needed when using The directives "authuser" and "authpassword" are not needed when using
Kerberos. They are defined to allow Asterisk to authenticate as a single Kerberos. They are defined to allow Asterisk to authenticate as a single
user that has access to all mailboxes as an alternative to Kerberos. user that has access to all mailboxes as an alternative to Kerberos.
\subsection{IMAP Folders} \subsection{IMAP Folders}
Besides INBOX, users should create "Old", "Work", "Family" and "Friends" Besides INBOX, users should create "Old", "Work", "Family" and "Friends"
IMAP folders at the same level of hierarchy as the INBOX. These will be IMAP folders at the same level of hierarchy as the INBOX. These will be
used as alternate folders for storing voicemail messages to mimic the used as alternate folders for storing voicemail messages to mimic the
behavior of the current (file-based) voicemail system. behavior of the current (file-based) voicemail system.
@ -103,22 +108,22 @@ behavior of the current (file-based) voicemail system.
As administrator you will have to decide if you want to send the voicemail As administrator you will have to decide if you want to send the voicemail
messages to a separate IMAP account or use each user's existing IMAP mailbox messages to a separate IMAP account or use each user's existing IMAP mailbox
for voicemail storage. The IMAP storage mechanism will work either way. for voicemail storage. The IMAP storage mechanism will work either way.
By implementing a single IMAP mailbox, the user will see voicemail messages By implementing a single IMAP mailbox, the user will see voicemail messages
appear in the same INBOX as other messages. The disadvantage of this method appear in the same INBOX as other messages. The disadvantage of this method
is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
expunge ALL messages marked for deletion when the user exits the voicemail expunge ALL messages marked for deletion when the user exits the voicemail
system, not just the VOICEMAIL messages marked for deletion. system, not just the VOICEMAIL messages marked for deletion.
By implementing separate IMAP mailboxes for voicemail and email, voicemail By implementing separate IMAP mailboxes for voicemail and email, voicemail
expunges will not remove regular email flagged for deletion. expunges will not remove regular email flagged for deletion.
\subsection{IMAP Server Implementations} \subsection{IMAP Server Implementations}
There are various IMAP server implementations, each supports a potentially There are various IMAP server implementations, each supports a potentially
different set of features. different set of features.
\subsubsection{UW IMAP-2005 or earlier} \subsubsection{UW IMAP-2005 or earlier}
@ -134,23 +139,23 @@ feature allow the system to expunge ONLY pertinent messages, instead of the
default behavior, which is to expunge ALL messages marked for deletion when default behavior, which is to expunge ALL messages marked for deletion when
EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk EXPUNGE is called. The IMAP storage mechanism is this version of Asterisk
will check if the UID\_EXPUNGE feature is supported by the server, and use it will check if the UID\_EXPUNGE feature is supported by the server, and use it
if possible. if possible.
\subsubsection{Cyrus IMAP} \subsubsection{Cyrus IMAP}
Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'. Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.
\subsection{Quota Support} \subsection{Quota Support}
If the IMAP server supports quotas, Asterisk will check the quota when If the IMAP server supports quotas, Asterisk will check the quota when
accessing voicemail. Currently only a warning is given to the user that accessing voicemail. Currently only a warning is given to the user that
their quota is exceeded. their quota is exceeded.
\subsection{Application Notes} \subsection{Application Notes}
Since the primary storage mechanism is IMAP, all message information that Since the primary storage mechanism is IMAP, all message information that
was previously stored in an associated text file, AND the recording itself, was previously stored in an associated text file, AND the recording itself,
is now stored in a single email message. This means that the .gsm recording is now stored in a single email message. This means that the .gsm recording
will ALWAYS be attached to the message (along with the user's preference of will ALWAYS be attached to the message (along with the user's preference of

68
doc/tex/jitterbuffer.tex
View File

@ -1,30 +1,30 @@
\subsubsection{The new jitterbuffer} \subsubsection{The new jitterbuffer}
You must add "jitterbuffer=yes" to either the [general] part of You must add "jitterbuffer=yes" to either the [general] part of
iax.conf, or to a peer or a user. (just like the old jitterbuffer). iax.conf, or to a peer or a user. (just like the old jitterbuffer).
Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the Also, you can set "maxjitterbuffer=n", which puts a hard-limit on the size of the
jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer jitterbuffer of "n milliseconds". It is not necessary to have the new jitterbuffer
on both sides of a call; it works on the receive side only. on both sides of a call; it works on the receive side only.
\subsubsection{PLC} \subsubsection{PLC}
The new jitterbuffer detects packet loss. PLC is done to try to recreate these The new jitterbuffer detects packet loss. PLC is done to try to recreate these
lost packets in the codec decoding stage, as the encoded audio is translated to slinear. lost packets in the codec decoding stage, as the encoded audio is translated to slinear.
PLC is also used to mask jitterbuffer growth. PLC is also used to mask jitterbuffer growth.
This facility is enabled by default in iLBC and speex, as it has no additional cost. This facility is enabled by default in iLBC and speex, as it has no additional cost.
This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting This facility can be enabled in adpcm, alaw, g726, gsm, lpc10, and ulaw by setting
genericplc => true in the [plc] section of codecs.conf. genericplc =$>$ true in the [plc] section of codecs.conf.
\subsubsection{Trunktimestamps} \subsubsection{Trunktimestamps}
To use this, both sides must be using Asterisk v1.2 or later. To use this, both sides must be using Asterisk v1.2 or later.
Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps Setting "trunktimestamps=yes" in iax.conf will cause your box to send 16-bit timestamps
for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer for each trunked frame inside of a trunk frame. This will enable you to use jitterbuffer
for an IAX2 trunk, something that was not possible in the old architecture. for an IAX2 trunk, something that was not possible in the old architecture.
The other side must also support this functionality, or else, well, bad things will happen. The other side must also support this functionality, or else, well, bad things will happen.
If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because If you don't use trunktimestamps, there's lots of ways the jitterbuffer can get confused because
timestamps aren't necessarily sent through the trunk correctly. timestamps aren't necessarily sent through the trunk correctly.
\subsubsection{Communication with Asterisk v1.0.x systems} \subsubsection{Communication with Asterisk v1.0.x systems}
@ -33,25 +33,25 @@ You can set up communication with v1.0.x systems with the new jitterbuffer, but
you can't use trunks with trunktimestamps in this communication. you can't use trunks with trunktimestamps in this communication.
If you are connecting to an Asterisk server with earlier versions of the software (1.0.x), If you are connecting to an Asterisk server with earlier versions of the software (1.0.x),
do not enable both jitterbuffer and trunking for the involved peers/users do not enable both jitterbuffer and trunking for the involved peers/users
in order to be able to communicate. Earlier systems will not support trunktimestamps. in order to be able to communicate. Earlier systems will not support trunktimestamps.
You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old You may also compile chan\_iax2.c without the new jitterbuffer, enabling the old
backwards compatible architecture. Look in the source code for instructions. backwards compatible architecture. Look in the source code for instructions.
\subsubsection{Testing and monitoring} \subsubsection{Testing and monitoring}
You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using You can test the effectiveness of PLC and the new jitterbuffer's detection of loss by using
the new CLI command "iax2 test losspct $<$n$>$". This will simulate n percent packet loss the new CLI command "iax2 test losspct $<$n$>$". This will simulate n percent packet loss
coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet coming \_in\_ to chan\_iax2. You should find that with PLC and the new JB, 10 percent packet
loss should lead to just a tiny amount of distortion, while without PLC, it would lead to loss should lead to just a tiny amount of distortion, while without PLC, it would lead to
silent gaps in your audio. silent gaps in your audio.
"iax2 show netstats" shows you statistics for each iax2 call you have up. "iax2 show netstats" shows you statistics for each iax2 call you have up.
The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s The columns are "RTT" which is the round-trip time for the last PING, and then a bunch of s
tats for both the local side (what you're receiving), and the remote side (what the other tats for both the local side (what you're receiving), and the remote side (what the other
end is telling us they are seeing). The remote stats may not be complete if the remote end is telling us they are seeing). The remote stats may not be complete if the remote
end isn't using the new jitterbuffer. end isn't using the new jitterbuffer.
The stats shown are: The stats shown are:
@ -65,34 +65,34 @@ The stats shown are:
\item Kpkts: The number of packets we've received / 1000. \item Kpkts: The number of packets we've received / 1000.
\end{itemize} \end{itemize}
\subsubsection{Reporting problems} \subsubsection{Reporting problems}
There's a couple of things that can make calls sound bad using the jitterbuffer: There's a couple of things that can make calls sound bad using the jitterbuffer:
\begin{enumerate} \begin{enumerate}
\item The JB and PLC can make your calls sound better, but they can't fix everything. \item The JB and PLC can make your calls sound better, but they can't fix everything.
If you lost 10 frames in a row, it can't possibly fix that. It really can't help much If you lost 10 frames in a row, it can't possibly fix that. It really can't help much
more than one or two consecutive frames. more than one or two consecutive frames.
\item Bad timestamps: If whatever is generating timestamps to be sent to you generates \item Bad timestamps: If whatever is generating timestamps to be sent to you generates
nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities nonsensical timestamps, it can confuse the jitterbuffer. In particular, discontinuities
in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40, in timestamps will really upset it: Things like timestamps sequences which go 0, 20, 40,
60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds 60, 80, 34000, 34020, 34040, 34060... It's going to think you've got about 34 seconds
of jitter in this case, etc.. of jitter in this case, etc..
The right solution to this is to find out what's causing the sender to send us such nonsense, The right solution to this is to find out what's causing the sender to send us such nonsense,
and fix that. But we should also figure out how to make the receiver more robust in and fix that. But we should also figure out how to make the receiver more robust in
cases like this. cases like this.
chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at chan\_iax2 will actually help fix this a bit if it's more than 3 seconds or so, but at
some point we should try to think of a better way to detect this kind of thing and some point we should try to think of a better way to detect this kind of thing and
resynchronize. resynchronize.
Different clock rates are handled very gracefully though; it will actually deal with a Different clock rates are handled very gracefully though; it will actually deal with a
sender sending 20\% faster or slower than you expect just fine. sender sending 20\% faster or slower than you expect just fine.
\item Really strange network delays: If your network "pauses" for like 5 seconds, and then \item Really strange network delays: If your network "pauses" for like 5 seconds, and then
when it restarts, you are sent some packets that are 5 seconds old, we are going to see when it restarts, you are sent some packets that are 5 seconds old, we are going to see
that as a lot of jitter. We already throw away up to the worst 20 frames like this, that as a lot of jitter. We already throw away up to the worst 20 frames like this,
though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case. though, and the "maxjitterbuffer" parameter should put a limit on what we do in this case.
\end{enumerate} \end{enumerate}

63
doc/tex/localchannel.tex
View File

@ -1,55 +1,55 @@
\subsection{Introduction} \subsection{Introduction}
chan\_local is a pseudo-channel. Use of this channel simply loops calls back chan\_local is a pseudo-channel. Use of this channel simply loops calls back
into the dialplan in a different context. Useful for recursive routing. into the dialplan in a different context. Useful for recursive routing.
\subsection{Syntax} \subsection{Syntax}
\begin{verbatim} \begin{verbatim}
Local/extension@context[/n] Local/extension@context[/{n|j}]
\end{verbatim} \end{verbatim}
Adding "/n" at the end of the string will make the Local channel not do a Adding "/n" at the end of the string will make the Local channel not do a
native transfer (the "n" stands for "n"o release) upon the remote end answering native transfer (the "n" stands for "n"o release) upon the remote end answering
the line. This is an esoteric, but important feature if you expect the Local the line. This is an esoteric, but important feature if you expect the Local
channel to handle calls exactly like a normal channel. If you do not have the channel to handle calls exactly like a normal channel. If you do not have the
"no release" feature set, then as soon as the destination (inside of the Local "no release" feature set, then as soon as the destination (inside of the Local
channel) answers the line, the variables and dial plan will revert back to that channel) answers the line, the variables and dial plan will revert back to that
of the original call, and the Local channel will become a zombie and be removed of the original call, and the Local channel will become a zombie and be removed
from the active channels list. This is desirable in some circumstances, but can from the active channels list. This is desirable in some circumstances, but can
result in unexpected dialplan behavior if you are doing fancy things with result in unexpected dialplan behavior if you are doing fancy things with
variables in your call handling. variables in your call handling.
There is another option that can be used with local channels, which is the "j" There is another option that can be used with local channels, which is the "j"
option. The "j" option must be used with the "n" option to make sure that the option. The "j" option must be used with the "n" option to make sure that the
local channel does not get optimized out of the call. This option will enable local channel does not get optimized out of the call. This option will enable
a jitterbuffer on the local channel. The jitterbuffer will be used to de-jitter a jitterbuffer on the local channel. The jitterbuffer will be used to de-jitter
audio that it receives from the channel that called the local channel. This is audio that it receives from the channel that called the local channel. This is
especially in the case of putting chan\_local in between an incoming SIP call especially in the case of putting chan\_local in between an incoming SIP call
and Asterisk applications, so that the incoming audio will be de-jittered. and Asterisk applications, so that the incoming audio will be de-jittered.
\subsection{Purpose} \subsection{Purpose}
The Local channel construct can be used to establish dialing into any part of The Local channel construct can be used to establish dialing into any part of
the dialplan. the dialplan.
Imagine you have a TE410P in your box. You want to do something for which you Imagine you have a TE410P in your box. You want to do something for which you
must use a Dial statement (for instance when dropping files in must use a Dial statement (for instance when dropping files in
\path{/var/spool/outgoing}) but you do want to be able to use your dialplans \path{/var/spool/outgoing}) but you do want to be able to use your dialplans
least-cost-routes or other intelligent stuff. What you could do before we had least-cost-routes or other intelligent stuff. What you could do before we had
chan\_local was create a cross-link between two ports of the TE410P and then chan\_local was create a cross-link between two ports of the TE410P and then
Dial out one port and in the other. This way you could control where the call Dial out one port and in the other. This way you could control where the call
was going. was going.
Of course, this was a nasty hack, and to make it more sensible, chan\_local was Of course, this was a nasty hack, and to make it more sensible, chan\_local was
built. built.
The "Local" channel driver allows you to convert an arbitrary extension into a The "Local" channel driver allows you to convert an arbitrary extension into a
channel. It is used in a variety of places, including agents, etc. channel. It is used in a variety of places, including agents, etc.
This also allows us to hop to contexts like a GoSub routine; See examples below. This also allows us to hop to contexts like a GoSub routine; See examples below.
\subsection{Examples} \subsection{Examples}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[inbound] ; here falls all incoming calls [inbound] ; here falls all incoming calls
exten => s,1,Answer exten => s,1,Answer
@ -60,18 +60,19 @@ exten => s,4,Hangup
[internal] ; here where our phones falls for default [internal] ; here where our phones falls for default
exten => 200,1,Dial(sip/blah) exten => 200,1,Dial(sip/blah)
exten => 200,102,VoiceMail(${EXTEN}@default) exten => 200,102,VoiceMail(${EXTEN}@default)
exten => 201,1,Dial(zap/1) exten => 201,1,Dial(zap/1)
exten => 201,102,VoiceMail(${EXTEN}@default) exten => 201,102,VoiceMail(${EXTEN}@default)
exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number exten => _0.,1,Dial(Zap/g1/${EXTEN:1}) ; outgoing calls with 0+number
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{Caveats} \subsection{Caveats}
If you use chan\_local from a call-file and you want to pass channel variables If you use chan\_local from a call-file and you want to pass channel variables
into your context, make sure you append the '/n', because otherwise into your context, make sure you append the '/n', because otherwise
chan\_local will 'optimize' itself out of the call-path, and the variables will chan\_local will 'optimize' itself out of the call-path, and the variables will
get lost. i.e. get lost. i.e.
\begin{verbatim} \begin{verbatim}

39
doc/tex/manager.tex
View File

@ -15,9 +15,9 @@ generate an initial response and data in the form list of events.
This format is created to make sure that extensive reports do not This format is created to make sure that extensive reports do not
block the manager interface fully. block the manager interface fully.
Management users are configured in the configuration file manager.conf and are Management users are configured in the configuration file manager.conf and are
given permissions for read and write, where write represents their ability given permissions for read and write, where write represents their ability
to perform this class of "action", and read represents their ability to to perform this class of "action", and read represents their ability to
receive this class of "event". receive this class of "event".
If you develop AMI applications, treat the headers If you develop AMI applications, treat the headers
@ -40,16 +40,17 @@ subscriptions and call limits)
\section{Command Syntax} \section{Command Syntax}
Management communication consists of tags of the form "header: value", Management communication consists of tags of the form "header: value",
terminated with an empty newline (\textbackslash r\textbackslash n) in the style of SMTP, HTTP, and terminated with an empty newline (\textbackslash r\textbackslash n) in
other headers. the style of SMTP, HTTP, and other headers.
The first tag MUST be one of the following: The first tag MUST be one of the following:
\begin{itemize} \begin{itemize}
\item Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time. \item Action: An action requested by the CLIENT to the Asterisk SERVER.
Only one "Action" may be outstanding at any time.
\item Response: A response to an action from the Asterisk SERVER to the CLIENT. \item Response: A response to an action from the Asterisk SERVER to the CLIENT.
\item Event: An event reported by the Asterisk SERVER to the CLIENT \item Event: An event reported by the Asterisk SERVER to the CLIENT
\end{itemize} \end{itemize}
\section{Manager commands} \section{Manager commands}
@ -107,7 +108,7 @@ Redirect with ExtraChannel:
Where 680 is an extension that sends you to a MeetMe room. Where 680 is an extension that sends you to a MeetMe room.
There are a number of GUI tools that use the manager interface, please search There are a number of GUI tools that use the manager interface, please search
the mailing list archives and the documentation page on the the mailing list archives and the documentation page on the
\url{http://www.asterisk.org} web site for more information. \url{http://www.asterisk.org} web site for more information.
@ -117,7 +118,7 @@ the mailing list archives and the documentation page on the
AccountCode: -- Account Code (cdr_manager) AccountCode: -- Account Code (cdr_manager)
ACL: <Y | N> -- Does ACL exist for object ? ACL: <Y | N> -- Does ACL exist for object ?
Action: <action> -- Request or notification of a particular action Action: <action> -- Request or notification of a particular action
Address-IP: -- IPaddress Address-IP: -- IPaddress
Address-Port: -- IP port number Address-Port: -- IP port number
Agent: <string> -- Agent name Agent: <string> -- Agent name
AMAflags: -- AMA flag (cdr_manager, sippeers) AMAflags: -- AMA flag (cdr_manager, sippeers)
@ -130,12 +131,12 @@ the mailing list archives and the documentation page on the
BillableSeconds: -- Billable seconds for call (cdr_manager) BillableSeconds: -- Billable seconds for call (cdr_manager)
CallerID: -- Caller id (name and number in Originate & cdr_manager) CallerID: -- Caller id (name and number in Originate & cdr_manager)
CallerID: -- CallerID number CallerID: -- CallerID number
Number or "<unknown>" or "unknown" Number or "<unknown>" or "unknown"
(should change to "<unknown>" in app_queue) (should change to "<unknown>" in app_queue)
CallerID1: -- Channel 1 CallerID (Link event) CallerID1: -- Channel 1 CallerID (Link event)
CallerID2: -- Channel 2 CallerID (Link event) CallerID2: -- Channel 2 CallerID (Link event)
CallerIDName: -- CallerID name CallerIDName: -- CallerID name
Name or "<unknown>" or "unknown" Name or "<unknown>" or "unknown"
(should change to "<unknown>" in app_queue) (should change to "<unknown>" in app_queue)
Callgroup: -- Call group for peer/user Callgroup: -- Call group for peer/user
CallsTaken: <num> -- Queue status variable CallsTaken: <num> -- Queue status variable
@ -188,19 +189,19 @@ the mailing list archives and the documentation page on the
Loginchan: -- Login channel for agent Loginchan: -- Login channel for agent
Logintime: <number> -- Login time for agent Logintime: <number> -- Login time for agent
Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount) Mailbox: -- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format MD5SecretExist: <Y | N> -- Whether secret exists in MD5 format
Membership: <string> -- "Dynamic" or "static" member in queue Membership: <string> -- "Dynamic" or "static" member in queue
Message: <text> -- Text message in ACKs, errors (explanation) Message: <text> -- Text message in ACKs, errors (explanation)
Mix: <bool> -- Boolean parameter (monitor) Mix: <bool> -- Boolean parameter (monitor)
NewMessages: <count> -- Count of new Mailbox messages (mailboxcount) NewMessages: <count> -- Count of new Mailbox messages (mailboxcount)
Newname: Newname:
ObjectName: -- Name of object in list ObjectName: -- Name of object in list
OldName: -- Something in Rename (channel.c) OldName: -- Something in Rename (channel.c)
OldMessages: <count> -- Count of old mailbox messages (mailboxcount) OldMessages: <count> -- Count of old mailbox messages (mailboxcount)
Outgoinglimit: -- SIP Peer outgoing limit Outgoinglimit: -- SIP Peer outgoing limit
Paused: <num> -- Queue member paused status Paused: <num> -- Queue member paused status
Peer: <tech/name> -- "channel" specifier :-) Peer: <tech/name> -- "channel" specifier :-)
PeerStatus: <tech/name> -- Peer status code PeerStatus: <tech/name> -- Peer status code
"Unregistered", "Registered", "Lagged", "Reachable" "Unregistered", "Registered", "Lagged", "Reachable"
Penalty: <num> -- Queue penalty Penalty: <num> -- Queue penalty
Priority: -- Extension priority Priority: -- Extension priority
@ -218,8 +219,8 @@ the mailing list archives and the documentation page on the
Reason: -- Originate reason code Reason: -- Originate reason code
Seconds: -- Seconds (Status) Seconds: -- Seconds (Status)
Secret: <password> -- Authentication secret (for login) Secret: <password> -- Authentication secret (for login)
SecretExist: <Y | N> -- Whether secret exists SecretExist: <Y | N> -- Whether secret exists
Shutdown: -- "Uncleanly", "Cleanly" Shutdown: -- "Uncleanly", "Cleanly"
SIP-AuthInsecure: SIP-AuthInsecure:
SIP-FromDomain: -- Peer FromDomain SIP-FromDomain: -- Peer FromDomain
SIP-FromUser: -- Peer FromUser SIP-FromUser: -- Peer FromUser

62
doc/tex/misdn.tex
View File

@ -1,7 +1,7 @@
\subsection{Introduction} \subsection{Introduction}
This package contains the mISDN Channel Driver for the Asterisk PBX. It This package contains the mISDN Channel Driver for the Asterisk PBX. It
supports every mISDN Hardware and provides an interface for asterisk. supports every mISDN Hardware and provides an interface for asterisk.
\subsection{Features} \subsection{Features}
@ -10,15 +10,15 @@ supports every mISDN Hardware and provides an interface for asterisk.
\item PP and PMP mode \item PP and PMP mode
\item BRI and PRI (with BNE1 and BN2E1 Cards) \item BRI and PRI (with BNE1 and BN2E1 Cards)
\item Hardware Bridging \item Hardware Bridging
\item DTMF Detection in HW+mISDNdsp \item DTMF Detection in HW+mISDNdsp
\item Display Messages on Phones (on those that support display msg) \item Display Messages on Phones (on those that support display msg)
\item app\_SendText \item app\_SendText
\item HOLD/RETRIEVE/TRANSFER on ISDN Phones : ) \item HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
\item Screen/ Not Screen User Number \item Screen/ Not Screen User Number
\item EchoCancellation \item EchoCancellation
\item Volume Control \item Volume Control
\item Crypting with mISDNdsp (Blowfish) \item Crypting with mISDNdsp (Blowfish)
\item Data (HDLC) callthrough \item Data (HDLC) callthrough
\item Data Calling (with app\_ptyfork +pppd) \item Data Calling (with app\_ptyfork +pppd)
\item Echo cancellation \item Echo cancellation
\item CallDeflection \item CallDeflection
@ -28,35 +28,35 @@ supports every mISDN Hardware and provides an interface for asterisk.
\subsection{Fast Installation Guide} \subsection{Fast Installation Guide}
It is easy to install mISDN and mISDNuser. This can be done by: It is easy to install mISDN and mISDNuser. This can be done by:
\begin{itemize} \begin{itemize}
\item You can download latest stable releases from \url{http://www.misdn.org/downloads/} \item You can download latest stable releases from \url{http://www.misdn.org/downloads/}
\item Just fetch the newest head of the GIT (mISDN provect moved from CVS) \item Just fetch the newest head of the GIT (mISDN provect moved from CVS)
In details this process described here: \url{http://www.misdn.org/index.php/GIT} In details this process described here: \url{http://www.misdn.org/index.php/GIT}
\end{itemize} \end{itemize}
then compile and install both with: then compile and install both with:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
cd mISDN ; cd mISDN ;
make && make install make && make install
\end{verbatim} \end{verbatim}
\end{astlisting}
(you will need at least your kernel headers to compile mISDN). (you will need at least your kernel headers to compile mISDN).
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
cd mISDNuser ; cd mISDNuser ;
make && make install make && make install
\end{verbatim} \end{verbatim}
\end{astlisting}
Now you can compile chan\_misdn, just by making asterisk: Now you can compile chan\_misdn, just by making asterisk:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
cd asterisk ; cd asterisk ;
./configure && make && make install ./configure && make && make install
\end{verbatim} \end{verbatim}
\end{astlisting}
That's all! That's all!
Follow the instructions in the mISDN Package for how to load the Kernel Follow the instructions in the mISDN Package for how to load the Kernel
@ -69,7 +69,7 @@ the mISDNuser package. Chan\_misdn works with both, the current release version
and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must
be fetched from cvs.isdn4linux.de. be fetched from cvs.isdn4linux.de.
You should use Kernels $>$= 2.6.9 You should use Kernels $>$= 2.6.9
\subsection{Configuration} \subsection{Configuration}
@ -77,12 +77,12 @@ You should use Kernels $>$= 2.6.9
First of all you must configure the mISDN drivers, please follow the First of all you must configure the mISDN drivers, please follow the
instructions in the mISDN package to do that, the main config file and config instructions in the mISDN package to do that, the main config file and config
script is: script is:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
/etc/init.d/misdn-init and /etc/init.d/misdn-init and
/etc/misdn-init.conf /etc/misdn-init.conf
\end{verbatim} \end{verbatim}
\end{astlisting}
Now you will want to configure the misdn.conf file which resides in the Now you will want to configure the misdn.conf file which resides in the
asterisk config directory (normally /etc/asterisk). asterisk config directory (normally /etc/asterisk).
@ -122,6 +122,7 @@ send incoming calls to in the Asterisk dial plan (extension.conf).
The dial string of chan\_misdn got more complex, because we added more features, The dial string of chan\_misdn got more complex, because we added more features,
so the generic dial string looks like: so the generic dial string looks like:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>] mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
@ -130,17 +131,18 @@ The Optionsstring looks Like:
the ":" character is the delimiter. the ":" character is the delimiter.
The available Optchars are: The available Optchars are:
d - Send display text on called phone, text is the optparam d - Send display text on called phone, text is the optparam
n - don't detect dtmf tones on called channel n - don't detect dtmf tones on called channel
h - make digital outgoing call h - make digital outgoing call
c - make crypted outgoing call, param is keyindex c - make crypted outgoing call, param is keyindex
e - perform echo cancellation on this channel, e - perform echo cancellation on this channel,
takes taps as arguments (32,64,128,256) takes taps as arguments (32,64,128,256)
s - send Non Inband DTMF as inband s - send Non Inband DTMF as inband
vr - rxgain control vr - rxgain control
vt - txgain control vt - txgain control
\end{verbatim} \end{verbatim}
\end{astlisting}
chan\_misdn registers a new dial plan application "misdn\_set\_opt" when chan\_misdn registers a new dial plan application "misdn\_set\_opt" when
loaded. This application takes the Optionsstring as argument. The Syntax is: loaded. This application takes the Optionsstring as argument. The Syntax is:
@ -155,7 +157,7 @@ incoming channel. So if you like to use static encryption, the scenario looks
as follows: as follows:
\begin{verbatim} \begin{verbatim}
Phone1 --> * Box 1 --> PSTN_TE Phone1 --> * Box 1 --> PSTN_TE
PSTN_TE --> * Box 2 --> Phone2 PSTN_TE --> * Box 2 --> Phone2
\end{verbatim} \end{verbatim}
@ -174,20 +176,21 @@ exten => ${CRYPT_MSN},2,dial(${PHONE2})
\subsection{mISDN CLI commands} \subsection{mISDN CLI commands}
At the Asterisk cli you can try to type in: At the Asterisk cli you can try to type in:
\begin{verbatim} \begin{verbatim}
misdn <tab> <tab> misdn <tab> <tab>
\end{verbatim} \end{verbatim}
Now you should see the misdn cli commands: Now you should see the misdn cli commands:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
- clean - clean
-> pid (cleans a broken call, use with care, leads often -> pid (cleans a broken call, use with care, leads often
to a segmentation fault) to a segmentation fault)
- send - send
-> display (sends a Text Message to a Asterisk channel, -> display (sends a Text Message to a Asterisk channel,
this channel must be an misdn channel) this channel must be an misdn channel)
- set - set
-> debug (sets debug level) -> debug (sets debug level)
@ -198,11 +201,12 @@ Now you should see the misdn cli commands:
-> stacks (shows the current ports, their protocols and states) -> stacks (shows the current ports, their protocols and states)
-> fullstacks (shows the current active and inactive misdn channels) -> fullstacks (shows the current active and inactive misdn channels)
- restart - restart
-> port (restarts given port (L2 Restart) ) -> port (restarts given port (L2 Restart) )
- reload (reloads misdn.conf) - reload (reloads misdn.conf)
\end{verbatim} \end{verbatim}
\end{astlisting}
You can only use "misdn send display" when an Asterisk channel is created and You can only use "misdn send display" when an Asterisk channel is created and
isdn is in the correct state. "correct state" means that you have established a isdn is in the correct state. "correct state" means that you have established a
@ -217,10 +221,10 @@ msn (callerid) of the Phone to send the text to.
\subsection{mISDN Variables} \subsection{mISDN Variables}
mISDN Exports/Imports a few Variables: mISDN Exports/Imports a few Variables:
\begin{verbatim} \begin{verbatim}
- MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you - MISDN_ADDRESS_COMPLETE : Is either set to 1 from the Provider, or you
can set it to 1 to force a sending complete. can set it to 1 to force a sending complete.
\end{verbatim} \end{verbatim}
@ -243,6 +247,7 @@ provide all the information needed.
Here are some examples of how to use chan\_misdn in the dialplan Here are some examples of how to use chan\_misdn in the dialplan
(extensions.conf): (extensions.conf):
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[globals] [globals]
OUT_PORT=1 ; The physical Port of the Card OUT_PORT=1 ; The physical Port of the Card
@ -254,6 +259,7 @@ exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello) exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n) exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)
\end{verbatim} \end{verbatim}
\end{astlisting}
On the last line, you will notice the last argument (Hello); this is sent On the last line, you will notice the last argument (Hello); this is sent
as Display Message to the Phone. as Display Message to the Phone.

22
doc/tex/privacy.tex
View File

@ -114,14 +114,16 @@ are those we know, and are doing so out of curiosity, there have been
these others from Jan 1st,2004 thru June 1st, 2004: these others from Jan 1st,2004 thru June 1st, 2004:
(the numbers may or may not be correct.) (the numbers may or may not be correct.)
603890zzzz hung up telemarket options. \begin{itemize}
"Integrated Sale" called a couple times. hung up in telemarket options \item 603890zzzz -- hung up telemarket options.
"UNITED STATES GOV" (-- maybe a military recruiter, trying to lure one of my sons). \item "Integrated Sale" -- called a couple times. hung up in telemarket options
800349zzzz -- hung up in charity intro \item "UNITED STATES GOV" -- maybe a military recruiter, trying to lure one of my sons.
800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts! \item 800349zzzz -- hung up in charity intro
216377zzzz -- hung up the magazine section \item 800349zzzz -- hung up in charity choices, intro, about the only one who actually travelled to the bitter bottom of the scripts!
626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices \item 216377zzzz -- hung up the magazine section
757821zzzz -- hung up in new magazine subscription options. \item 626757zzzz = "LIR " (pronounced "Liar"?) hung up in telemarket intro, then choices
\item 757821zzzz -- hung up in new magazine subscription options.
\end{itemize}
That averages out to maybe 1 a month. That puts into question whether That averages out to maybe 1 a month. That puts into question whether
the ratio of the amount of labor it took to make the scripts versus the ratio of the amount of labor it took to make the scripts versus
@ -165,6 +167,7 @@ There are some variations, and these will be explained in due course.
To use these options, set your Dial to something like: To use these options, set your Dial to something like:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmPA(beep)) exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmPA(beep))
or or
@ -172,6 +175,7 @@ exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmP(something)A(beep))
or or
exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmpA(beep)) exten => 3,3,Dial(Zap/5r3&Zap/6r3,35,tmpA(beep))
\end{verbatim} \end{verbatim}
\end{astlisting}
The 't' allows the dialed party to transfer the call using '\#'. It's The 't' allows the dialed party to transfer the call using '\#'. It's
optional. optional.
@ -244,10 +248,12 @@ having to supply their name, which shortens their call a bit.
Next of all, these intros can be used in voicemail, played over Next of all, these intros can be used in voicemail, played over
loudspeakers, and perhaps other nifty things. For instance: loudspeakers, and perhaps other nifty things. For instance:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
exten => s,6,Set(PATH=/var/lib/asterisk/sounds/priv-callerintros) exten => s,6,Set(PATH=/var/lib/asterisk/sounds/priv-callerintros)
exten => s,7,System(/usr/bin/play ${PATH}/${CALLERID(num)}.gsm&,0) exten => s,7,System(/usr/bin/play ${PATH}/${CALLERID(num)}.gsm&,0)
\end{verbatim} \end{verbatim}
\end{astlisting}
When a call comes in at the house, the above priority gets executed, When a call comes in at the house, the above priority gets executed,
and the callers intro is played over the phone systems speakers. This and the callers intro is played over the phone systems speakers. This

34
doc/tex/queuelog.tex
View File

@ -2,16 +2,16 @@ In order to properly manage ACD queues, it is important to be able to
keep track of details of call setups and teardowns in much greater detail keep track of details of call setups and teardowns in much greater detail
than traditional call detail records provide. In order to support this, than traditional call detail records provide. In order to support this,
extensive and detailed tracing of every queued call is stored in the extensive and detailed tracing of every queued call is stored in the
queue log, located (by default) in /var/log/asterisk/queue\_log. queue log, located (by default) in \path{/var/log/asterisk/queue_log}.
These are the events (and associated information) in the queue log: These are the events (and associated information) in the queue log:
\textbf{ABANDON(position|origposition|waittime)} \textbf{ABANDON(position$|$origposition$|$waittime)}
The caller abandoned their position in the queue. The position is the The caller abandoned their position in the queue. The position is the
caller's position in the queue when they hungup, the origposition is caller's position in the queue when they hungup, the origposition is
the original position the caller was when they first entered the the original position the caller was when they first entered the
queue, and the waittime is how long the call had been waiting in the queue, and the waittime is how long the call had been waiting in the
queue at the time of disconnect. queue at the time of disconnect.
\textbf{AGENTDUMP} \textbf{AGENTDUMP}
@ -26,26 +26,26 @@ The agent logged in. The channel is recorded.
The callback agent logged in. The login extension and context is recorded. The callback agent logged in. The login extension and context is recorded.
\textbf{AGENTLOGOFF(channel|logintime)} \textbf{AGENTLOGOFF(channel$|$logintime)}
The agent logged off. The channel is recorded, along with the total time The agent logged off. The channel is recorded, along with the total time
the agent was logged in. the agent was logged in.
\textbf{AGENTCALLBACKLOGOFF(exten@context|logintime|reason)} \textbf{AGENTCALLBACKLOGOFF(exten@context$|$logintime$|$reason)}
The callback agent logged off. The last login extension and context is The callback agent logged off. The last login extension and context is
recorded, along with the total time the agent was logged in, and the recorded, along with the total time the agent was logged in, and the
reason for the logoff if it was not a normal logoff reason for the logoff if it was not a normal logoff
(e.g., Autologoff, Chanunavail) (e.g., Autologoff, Chanunavail)
\textbf{COMPLETEAGENT(holdtime|calltime|origposition)} \textbf{COMPLETEAGENT(holdtime$|$calltime$|$origposition)}
The caller was connected to an agent, and the call was terminated normally The caller was connected to an agent, and the call was terminated normally
by the *agent*. The caller's hold time and the length of the call are both by the *agent*. The caller's hold time and the length of the call are both
recorded. The caller's original position in the queue is recorded in recorded. The caller's original position in the queue is recorded in
origposition. origposition.
\textbf{COMPLETECALLER(holdtime|calltime|origposition)} \textbf{COMPLETECALLER(holdtime$|$calltime$|$origposition)}
The caller was connected to an agent, and the call was terminated normally The caller was connected to an agent, and the call was terminated normally
by the *caller*. The caller's hold time and the length of the call are both by the *caller*. The caller's hold time and the length of the call are both
@ -56,7 +56,7 @@ origposition.
The configuration has been reloaded (e.g. with asterisk -rx reload) The configuration has been reloaded (e.g. with asterisk -rx reload)
\textbf{CONNECT(holdtime|bridgedchanneluniqueid|ringtime)} \textbf{CONNECT(holdtime$|$bridgedchanneluniqueid$|$ringtime)}
The caller was connected to an agent. Hold time represents the amount The caller was connected to an agent. Hold time represents the amount
of time the caller was on hold. The bridged channel unique ID contains of time the caller was on hold. The bridged channel unique ID contains
@ -65,27 +65,27 @@ is useful when trying to link recording filenames to a particular
call in the queue. Ringtime represents the time the queue members phone call in the queue. Ringtime represents the time the queue members phone
was ringing prior to being answered. was ringing prior to being answered.
\textbf{ENTERQUEUE(url|callerid)} \textbf{ENTERQUEUE(url$|$callerid)}
A call has entered the queue. URL (if specified) and Caller*ID are placed A call has entered the queue. URL (if specified) and Caller*ID are placed
in the log. in the log.
\textbf{EXITEMPTY(position|origposition|waittime)} \textbf{EXITEMPTY(position$|$origposition$|$waittime)}
The caller was exited from the queue forcefully because the queue had no The caller was exited from the queue forcefully because the queue had no
reachable members and it's configured to do that to callers when there reachable members and it's configured to do that to callers when there
are no reachable members. The position is the caller's position in the are no reachable members. The position is the caller's position in the
queue when they hungup, the origposition is the original position the queue when they hungup, the origposition is the original position the
caller was when they first entered the queue, and the waittime is how caller was when they first entered the queue, and the waittime is how
long the call had been waiting in the queue at the time of disconnect. long the call had been waiting in the queue at the time of disconnect.
\textbf{EXITWITHKEY(key|position|origposition|waittime)} \textbf{EXITWITHKEY(key$|$position$|$origposition$|$waittime)}
The caller elected to use a menu key to exit the queue. The key and The caller elected to use a menu key to exit the queue. The key and
the caller's position in the queue are recorded. The caller's entry the caller's position in the queue are recorded. The caller's entry
position and amoutn of time waited is also recorded. position and amoutn of time waited is also recorded.
\textbf{EXITWITHTIMEOUT(position|origposition|waittime)} \textbf{EXITWITHTIMEOUT(position$|$origposition$|$waittime)}
The caller was on hold too long and the timeout expired. The position in the The caller was on hold too long and the timeout expired. The position in the
queue when the timeout occurred, the entry position, and the amount of time queue when the timeout occurred, the entry position, and the amount of time
@ -103,10 +103,10 @@ member!
\textbf{SYSCOMPAT} \textbf{SYSCOMPAT}
A call was answered by an agent, but the call was dropped because the A call was answered by an agent, but the call was dropped because the
channels were not compatible. channels were not compatible.
\textbf{TRANSFER(extension|context|holdtime|calltime)} \textbf{TRANSFER(extension$|$context$|$holdtime$|$calltime)}
Caller was transferred to a different extension. Context and extension Caller was transferred to a different extension. Context and extension
are recorded. The caller's hold time and the length of the call are both are recorded. The caller's hold time and the length of the call are both

6
doc/tex/queues-with-callback-members.tex
View File

@ -471,7 +471,7 @@ context agents
\end{verbatim} \end{verbatim}
\end{astlisting} \end{astlisting}
In the above, the variables \${RAQUEL}, etc stand for In the above, the variables \$\{RAQUEL\}, etc stand for
actual devices to ring that person's actual devices to ring that person's
phone (like Zap/37). phone (like Zap/37).
@ -513,7 +513,7 @@ macro callagent(device,exten)
\end{verbatim} \end{verbatim}
\end{astlisting} \end{astlisting}
In the callagent macro above, the \${exten} will In the callagent macro above, the \$\{exten\} will
be 6121, or 6165, etc, which is the extension of the agent. be 6121, or 6165, etc, which is the extension of the agent.
The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line The use of the GROUP\_COUNT, and OUTBOUND\_GROUP follow this line
@ -522,7 +522,7 @@ current priority. If some of those agents are already talking, they
would get bothersome call-waiting tones. To avoid this inconvenience, would get bothersome call-waiting tones. To avoid this inconvenience,
when an agent gets a call, the OUTBOUND\_GROUP assigns that when an agent gets a call, the OUTBOUND\_GROUP assigns that
conversation to the group specified, for instance 6171@agents. conversation to the group specified, for instance 6171@agents.
The \${GROUP\_COUNT()} variable on a subsequent call should return The \$\{GROUP\_COUNT()\} variable on a subsequent call should return
"1" for that group. If GROUP\_COUNT returns 1, then the busy() "1" for that group. If GROUP\_COUNT returns 1, then the busy()
is returned without actually trying to dial the agent. is returned without actually trying to dial the agent.

30
doc/tex/realtime.tex
View File

@ -1,19 +1,19 @@
\subsubsection{Introduction} \subsubsection{Introduction}
The Asterisk Realtime Architecture is a new set of drivers and The Asterisk Realtime Architecture is a new set of drivers and
functions implemented in Asterisk. functions implemented in Asterisk.
The benefits of this architecture are many, both from a code management The benefits of this architecture are many, both from a code management
standpoint and from an installation perspective. standpoint and from an installation perspective.
The ARA is designed to be independent of storage. Currently, most The ARA is designed to be independent of storage. Currently, most
drivers are based on SQL, but the architecture should be able to handle drivers are based on SQL, but the architecture should be able to handle
other storage methods in the future, like LDAP. other storage methods in the future, like LDAP.
The main benefit comes in the database support. In Asterisk v1.0 some The main benefit comes in the database support. In Asterisk v1.0 some
functions supported MySQL database, some PostgreSQL and other ODBC. functions supported MySQL database, some PostgreSQL and other ODBC.
With the ARA, we have a unified database interface internally in Asterisk, With the ARA, we have a unified database interface internally in Asterisk,
so if one function supports database integration, all databases that has a so if one function supports database integration, all databases that has a
realtime driver will be supported in that function. realtime driver will be supported in that function.
Currently there are three realtime database drivers: Currently there are three realtime database drivers:
@ -22,7 +22,7 @@ Currently there are three realtime database drivers:
\item ODBC: Support for UnixODBC, integrated into Asterisk \item ODBC: Support for UnixODBC, integrated into Asterisk
The UnixODBC subsystem supports many different databases, The UnixODBC subsystem supports many different databases,
please check \url{www.unixodbc.org} for more information. please check \url{www.unixodbc.org} for more information.
\item MySQL: Found in the asterisk-addons subversion repository on svn.digium.com \item MySQL: Found in the asterisk-addons subversion repository on \url{svn.digium.com}
\item PostgreSQL: Native support for Postgres, integrated into Asterisk \item PostgreSQL: Native support for Postgres, integrated into Asterisk
\end{itemize} \end{itemize}
@ -30,7 +30,7 @@ Currently there are three realtime database drivers:
The ARA realtime mode is used to dynamically load and update objects. The ARA realtime mode is used to dynamically load and update objects.
This mode is used in the SIP and IAX2 channels, as well as in the voicemail This mode is used in the SIP and IAX2 channels, as well as in the voicemail
system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS system. For SIP and IAX2 this is similar to the v1.0 MYSQL\_FRIENDS
functionality. With the ARA, we now support many more databases for functionality. With the ARA, we now support many more databases for
dynamic configuration of phones. dynamic configuration of phones.
@ -41,13 +41,13 @@ from a database.
\subsubsection{Realtime SIP friends} \subsubsection{Realtime SIP friends}
The SIP realtime objects are users and peers that are loaded in memory The SIP realtime objects are users and peers that are loaded in memory
when needed, then deleted. This means that Asterisk currently can't handle when needed, then deleted. This means that Asterisk currently can't handle
voicemail notification and NAT keepalives for these peers. Other than that, voicemail notification and NAT keepalives for these peers. Other than that,
most of the functionality works the same way for realtime friends as for most of the functionality works the same way for realtime friends as for
the ones in static configuration. the ones in static configuration.
With caching, the device stays in memory for a specified time. More With caching, the device stays in memory for a specified time. More
information about this is to be found in the sip.conf sample file. information about this is to be found in the sip.conf sample file.
\subsubsection{Realtime H.323 friends} \subsubsection{Realtime H.323 friends}
@ -58,7 +58,7 @@ dynamic realtime objects.
\subsubsection{New function in the dial plan: The Realtime Switch} \subsubsection{New function in the dial plan: The Realtime Switch}
The realtime switch is more than a port of functionality in v1.0 to the The realtime switch is more than a port of functionality in v1.0 to the
new architecture, this is a new feature of Asterisk based on the new architecture, this is a new feature of Asterisk based on the
ARA. The realtime switch lets your Asterisk server do database lookups ARA. The realtime switch lets your Asterisk server do database lookups
of extensions in realtime from your dial plan. You can have many Asterisk of extensions in realtime from your dial plan. You can have many Asterisk
servers sharing a dynamically updated dial plan in real time with this servers sharing a dynamically updated dial plan in real time with this
@ -71,12 +71,12 @@ extension name or pattern matching.
The realtime Architecture lets you store all of your configuration in The realtime Architecture lets you store all of your configuration in
databases and reload it whenever you want. You can force a reload over databases and reload it whenever you want. You can force a reload over
the AMI, Asterisk Manager Interface or by calling Asterisk from a the AMI, Asterisk Manager Interface or by calling Asterisk from a
shell script with shell script with
asterisk -rx "reload" asterisk -rx "reload"
You may also dynamically add SIP and IAX devices and extensions You may also dynamically add SIP and IAX devices and extensions
and making them available without a reload, by using the realtime and making them available without a reload, by using the realtime
objects and the realtime switch. objects and the realtime switch.
@ -101,14 +101,14 @@ Defined well-known family names are:
\begin{itemize} \begin{itemize}
\item sippeers, sipusers - SIP peers and users \item sippeers, sipusers - SIP peers and users
\item iaxpeers, iaxusers - IAX2 peers and users \item iaxpeers, iaxusers - IAX2 peers and users
\item voicemail - Voicemail accounts \item voicemail - Voicemail accounts
\item queues - Queues \item queues - Queues
\item queue\_members - Queue members \item queue\_members - Queue members
\item extensions - Realtime extensions (switch) \item extensions - Realtime extensions (switch)
\end{itemize} \end{itemize}
Voicemail storage with the support of ODBC described in file Voicemail storage with the support of ODBC described in file
docs/odbcstorage.tex (\ref{odbcstorage}). \path{docs/odbcstorage.tex} (\ref{odbcstorage}).
\subsubsection{Limitations} \subsubsection{Limitations}

14
doc/tex/security.tex
View File

@ -1,11 +1,11 @@
\subsection{Introduction} \subsection{Introduction}
PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION. PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION.
IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR
FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES. FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES.
Asterisk security involves both network security (encryption, authentication) Asterisk security involves both network security (encryption, authentication)
as well as dialplan security (authorization - who can access services in as well as dialplan security (authorization - who can access services in
your pbx). If you are setting up Asterisk in production use, please make your pbx). If you are setting up Asterisk in production use, please make
sure you understand the issues involved. sure you understand the issues involved.
@ -37,7 +37,7 @@ INCOMING CONNECTIONS.
You should consider that if any channel, incoming line, etc can enter an You should consider that if any channel, incoming line, etc can enter an
extension context that it has the capability of accessing any extension extension context that it has the capability of accessing any extension
within that context. within that context.
Therefore, you should NOT allow access to outgoing or toll services in Therefore, you should NOT allow access to outgoing or toll services in
contexts that are accessible (especially without a password) from incoming contexts that are accessible (especially without a password) from incoming
@ -46,12 +46,15 @@ stations within you network. In particular, never ever put outgoing toll
services in the "default" context. To make things easier, you can include services in the "default" context. To make things easier, you can include
the "default" context within other private contexts by using: the "default" context within other private contexts by using:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
include => default include => default
\end{verbatim} \end{verbatim}
\end{astlisting}
in the appropriate section. A well designed PBX might look like this: in the appropriate section. A well designed PBX might look like this:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[longdistance] [longdistance]
exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1}) exten => _91NXXNXXXXXX,1,Dial(Zap/g2/${EXTEN:1})
@ -64,13 +67,14 @@ include => default
[default] [default]
exten => 6123,Dial(Zap/1) exten => 6123,Dial(Zap/1)
\end{verbatim} \end{verbatim}
\end{astlisting}
DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT. There
isn't really a security reason, it just will keep people from wanting to isn't really a security reason, it just will keep people from wanting to
play with your Asterisk setup remotely. play with your Asterisk setup remotely.
\subsection{Log Security} \subsection{Log Security}
Please note that the Asterisk log files, as well as information printed to the Please note that the Asterisk log files, as well as information printed to the
Asterisk CLI, may contain sensitive information such as passwords and call Asterisk CLI, may contain sensitive information such as passwords and call
history. Keep this in mind when providing access to these resources. history. Keep this in mind when providing access to these resources.

33
doc/tex/sla.tex
View File

@ -56,13 +56,14 @@ An SLA trunk is a mapping between a virtual trunk and a real Asterisk device.
This device may be an analog FXO line, or something like a SIP trunk. A trunk This device may be an analog FXO line, or something like a SIP trunk. A trunk
must be configured in two places. First, configure the device itself in the must be configured in two places. First, configure the device itself in the
channel specific configuration file such as zapata.conf or sip.conf. Once the channel specific configuration file such as zapata.conf or sip.conf. Once the
trunk is configured, then map it to an SLA trunk in sla.conf. trunk is configured, then map it to an SLA trunk in sla.conf.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line1] [line1]
type=trunk type=trunk
device=Zap/1 device=Zap/1
\end{verbatim} \end{verbatim}
\end{astlisting}
Be sure to configure the trunk's context to be the same one that is set for the Be sure to configure the trunk's context to be the same one that is set for the
"autocontext" option in sla.conf if automatic dialplan configuration is used. "autocontext" option in sla.conf if automatic dialplan configuration is used.
@ -84,26 +85,27 @@ going to say that they are calling the number "12564286000". Also, let's say
that the numbers that are valid for calling out this trunk are NANP numbers, that the numbers that are valid for calling out this trunk are NANP numbers,
of the form \_1NXXNXXXXXX. of the form \_1NXXNXXXXXX.
In sip.conf, there would be an entry for [mytrunk]. For [mytrunk], In sip.conf, there would be an entry for [mytrunk]. For [mytrunk],
set context=line4. set context=line4.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line4] [line4]
type=trunk type=trunk
device=Local/disa@line4_outbound device=Local/disa@line4_outbound
\end{verbatim} \end{verbatim}
\end{astlisting}
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line4] [line4]
exten => 12564286000,1,SLATrunk(line4) exten => 12564286000,1,SLATrunk(line4)
[line4_outbound] [line4_outbound]
exten => disa,1,Disa(no-password,line4_outbound) exten => disa,1,Disa(no-password,line4_outbound)
exten => _1NXXNXXXXXX,1,Dial(SIP/\${EXTEN}@mytrunk) exten => _1NXXNXXXXXX,1,Dial(SIP/${EXTEN}@mytrunk)
\end{verbatim} \end{verbatim}
\end{astlisting}
So, when a station picks up their phone and connects to line 4, they are So, when a station picks up their phone and connects to line 4, they are
connected to the local dialplan. The Disa application plays dialtone to the connected to the local dialplan. The Disa application plays dialtone to the
@ -116,8 +118,9 @@ SIP trunk.
An SLA station is a mapping between a virtual station and a real Asterisk device. An SLA station is a mapping between a virtual station and a real Asterisk device.
Currently, the only channel driver that has all of the features necessary to Currently, the only channel driver that has all of the features necessary to
support an SLA environment is chan\_sip. So, to configure a SIP phone to use support an SLA environment is chan\_sip. So, to configure a SIP phone to use
as a station, you must configure sla.conf and sip.conf. as a station, you must configure sla.conf and sip.conf.
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[station1] [station1]
type=station type=station
@ -125,6 +128,7 @@ device=SIP/station1
trunk=line1 trunk=line1
trunk=line2 trunk=line2
\end{verbatim} \end{verbatim}
\end{astlisting}
Here are some hints on configuring a SIP phone for use with SLA: Here are some hints on configuring a SIP phone for use with SLA:
@ -141,7 +145,7 @@ Here are some hints on configuring a SIP phone for use with SLA:
Let's say this phone is called "station1" in sla.conf, and it uses trunks Let's say this phone is called "station1" in sla.conf, and it uses trunks
named "line1" and line2". named "line1" and line2".
\begin{enumerate} \begin{enumerate}
\item Two line buttons must be configured to subscribe to the state of the \item Two line buttons must be configured to subscribe to the state of the
following extensions: following extensions:
- station1\_line1 - station1\_line1
@ -165,6 +169,7 @@ This is an example of the most basic SLA setup. It uses the automatic
dialplan generation so the configuration is minimal. dialplan generation so the configuration is minimal.
sla.conf: sla.conf:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line1] [line1]
type=trunk type=trunk
@ -190,8 +195,8 @@ device=SIP/station2
[station3](station) [station3](station)
device=SIP/station3 device=SIP/station3
\end{verbatim} \end{verbatim}
\end{astlisting}
With this configuration, the dialplan is generated automatically. The first With this configuration, the dialplan is generated automatically. The first
zap channel should have its context set to "line1" and the second should be zap channel should have its context set to "line1" and the second should be
@ -199,6 +204,7 @@ set to "line2" in zapata.conf. In sip.conf, station1, station2, and station3
should all have their context set to "sla\_stations". should all have their context set to "sla\_stations".
For reference, here is the automatically generated dialplan for this situation: For reference, here is the automatically generated dialplan for this situation:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line1] [line1]
exten => s,1,SLATrunk(line1) exten => s,1,SLATrunk(line1)
@ -225,7 +231,7 @@ exten => station3_line1,1,SLAStation(station3_line1)
exten => station3_line2,hint,SLA:station3_line2 exten => station3_line2,hint,SLA:station3_line2
exten => station3_line2,1,SLAStation(station3_line2) exten => station3_line2,1,SLAStation(station3_line2)
\end{verbatim} \end{verbatim}
\end{astlisting}
\subsection{SLA and Voicemail} \subsection{SLA and Voicemail}
\label{voicemail} \label{voicemail}
@ -247,6 +253,7 @@ NANP numbers for outbound calls, or 8500 for checking voicemail.
sla.conf: sla.conf:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[line1] [line1]
type=trunk type=trunk
@ -271,9 +278,10 @@ device=SIP/station2
device=SIP/station3 device=SIP/station3
\end{verbatim} \end{verbatim}
\end{astlisting}
extensions.conf: extensions.conf:
\begin{astlisting}
\begin{verbatim} \begin{verbatim}
[macro-slaline] [macro-slaline]
exten => s,1,SLATrunk(${ARG1}) exten => s,1,SLATrunk(${ARG1})
@ -318,6 +326,7 @@ exten => station3_line2,hint,SLA:station3_line2
exten => station3_line2,1,SLAStation(station3_line2) exten => station3_line2,1,SLAStation(station3_line2)
\end{verbatim} \end{verbatim}
\end{astlisting}
\section{Call Handling} \section{Call Handling}
\subsection{Summary} \subsection{Summary}