diff options
Diffstat (limited to 'doc/tex/channelvariables.tex')
| -rw-r--r-- | doc/tex/channelvariables.tex | 1066 |
1 files changed, 0 insertions, 1066 deletions
diff --git a/doc/tex/channelvariables.tex b/doc/tex/channelvariables.tex deleted file mode 100644 index d0aeae6ea..000000000 --- a/doc/tex/channelvariables.tex +++ /dev/null @@ -1,1066 +0,0 @@ -\section{Introduction} - -There are two levels of parameter evaluation done in the Asterisk -dial plan in extensions.conf. -\begin{enumerate} -\item The first, and most frequently used, is the substitution of variable - references with their values. -\item Then there are the evaluations of expressions done in \$[ .. ]. - This will be discussed below. -\end{enumerate} -Asterisk has user-defined variables and standard variables set -by various modules in Asterisk. These standard variables are -listed at the end of this document. - -\section{Parameter Quoting} -\begin{astlisting} -\begin{verbatim} -exten => s,5,BackGround,blabla -\end{verbatim} -\end{astlisting} -The parameter (blabla) can be quoted ("blabla"). In this case, a -comma does not terminate the field. However, the double quotes -will be passed down to the Background command, in this example. - -Also, characters special to variable substitution, expression evaluation, etc -(see below), can be quoted. For example, to literally use a \$ on the -string "\$1231", quote it with a preceding \textbackslash. Special characters that must -be quoted to be used, are [ ] \$ " \textbackslash. (to write \textbackslash itself, use \textbackslash). - -These Double quotes and escapes are evaluated at the level of the -asterisk config file parser. - -Double quotes can also be used inside expressions, as discussed below. - -\section{Variables} - -Parameter strings can include variables. Variable names are arbitrary strings. -They are stored in the respective channel structure. - -To set a variable to a particular value, do: -\begin{astlisting} -\begin{verbatim} - exten => 1,2,Set(varname=value) -\end{verbatim} -\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, -do: -\begin{astlisting} -\begin{verbatim} - exten => 1,2,Set(koko=${blabla}${lala}) -\end{verbatim} -\end{astlisting} - -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 -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 -(before the =) a variable name, so: -\begin{astlisting} -\begin{verbatim} - exten => 1,2,Set(koko=lala) - exten => 1,3,Set(${koko}=blabla) -\end{verbatim} -\end{astlisting} -stores to the variable "koko" the value "lala" and to variable "lala" the -value "blabla". - -In fact, everything contained \$\{here\} is just replaced with the value of -the variable "here". - -\section{Variable Inheritance} - -Variable names which are prefixed by "\_" will be inherited to channels -that are created in the process of servicing the original channel in -which the variable was set. When the inheritance takes place, the -prefix will be removed in the channel inheriting the variable. If the -name is prefixed by "\_\_" in the channel, then the variable is -inherited and the "\_\_" will remain intact in the new channel. - -In the dialplan, all references to these variables refer to the same -variable, regardless of having a prefix or not. Note that setting any -version of the variable removes any other version of the variable, -regardless of prefix. - -\subsection{Example} -\begin{astlisting} -\begin{verbatim} -Set(__FOO=bar) ; Sets an inherited version of "FOO" variable -Set(FOO=bar) ; Removes the inherited version and sets a local - ; variable. -\end{verbatim} -\end{astlisting} - -However, NoOp(\$\{\_\_FOO\}) is identical to NoOp(\$\{FOO\}) - -\section{Selecting Characters from Variables} - -The format for selecting characters from a variable can be expressed as: -\begin{astlisting} -\begin{verbatim} - ${variable_name[:offset[:length]]} -\end{verbatim} -\end{astlisting} -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 -skip from the beginning of the string to the variable name. -\begin{astlisting} -\begin{verbatim} - ; Remove the first character of extension, save in "number" variable - exten => _9X.,1,Set(number=${EXTEN:1}) -\end{verbatim} -\end{astlisting} -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 -dial a number to access an outside line, but do not wish to pass the first -digit. - -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 -example will save the numbers 1234 to the 'number' variable, still assuming -we've dialed 918005551234. -\begin{astlisting} -\begin{verbatim} - ; Remove everything before the last four digits of the dialed string - exten => _9X.,1,Set(number=${EXTEN:-4}) -\end{verbatim} -\end{astlisting} -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 -variable name. The following example will save the numbers 555 to the 'number' -variable. -\begin{astlisting} -\begin{verbatim} - ; Only save the middle numbers 555 from the string 918005551234 - exten => _9X.,1,Set(number=${EXTEN:5:3}) -\end{verbatim} -\end{astlisting} -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 -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 -previous example). -\begin{astlisting} -\begin{verbatim} - ; Save the numbers 555 to the 'number' variable - exten => _9X.,1,Set(number=${EXTEN:-7:3}) -\end{verbatim} -\end{astlisting} -If a negative length value is entered, Asterisk will remove that many characters -from the end of the string. -\begin{astlisting} -\begin{verbatim} - ; Set pin to everything but the trailing #. - exten => _XXXX#,1,Set(pin=${EXTEN:0:-1}) -\end{verbatim} -\end{astlisting} - -\section{Expressions} - -Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is -considered as an expression and it is evaluated. Evaluation works similar to -(but is done on a later stage than) variable substitution: the expression -(including the square brackets) is replaced by the result of the expression -evaluation. - -For example, after the sequence: -\begin{astlisting} -\begin{verbatim} -exten => 1,1,Set(lala=$[1 + 2]) -exten => 1,2,Set(koko=$[2 * ${lala}]) -\end{verbatim} -\end{astlisting} -the value of variable koko is "6". - -and, further: -\begin{astlisting} -\begin{verbatim} -exten => 1,1,Set,(lala=$[ 1 + 2 ]); -\end{verbatim} -\end{astlisting} -will parse as intended. Extra spaces are ignored. - - -\subsection{Spaces Inside Variables Values} - -If the variable being evaluated contains spaces, there can be problems. - -For these cases, double quotes around text that may contain spaces -will force the surrounded text to be evaluated as a single token. -The double quotes will be counted as part of that lexical token. - -As an example: - -\begin{astlisting} -\begin{verbatim} -exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) -\end{verbatim} -\end{astlisting} - -The variable CALLERID(name) could evaluate to "DELOREAN MOTORS" (with a space) -but the above will evaluate to: - -\begin{verbatim} -"DELOREAN MOTORS" : "Privacy Manager" -\end{verbatim} - -and will evaluate to 0. - -The above without double quotes would have evaluated to: - -\begin{verbatim} -DELOREAN MOTORS : Privacy Manager -\end{verbatim} - -and will result in syntax errors, because token DELOREAN is immediately -followed by token MOTORS and the expression parser will not know how to -evaluate this expression, because it does not match its grammar. - -\subsection{Operators} - -Operators are listed below in order of increasing precedence. Operators -with equal precedence are grouped within \{ \} symbols. - -\begin{itemize} - \item \verb!expr1 | expr2! - - Return the evaluation of expr1 if it is neither an empty string - nor zero; otherwise, returns the evaluation of expr2. - - \item \verb!expr1 & expr2! - - Return the evaluation of expr1 if neither expression evaluates to - an empty string or zero; otherwise, returns zero. - - \item \verb+expr1 {=, >, >=, <, <=, !=} expr2+ - - Return the results of floating point comparison if both arguments are - numbers; otherwise, returns the results of string comparison - using the locale-specific collation sequence. The result of each - comparison is 1 if the specified relation is true, or 0 if the - relation is false. - - \item \verb!expr1 {+, -} expr2! - - Return the results of addition or subtraction of floating point-valued - arguments. - - \item \verb!expr1 {*, /, %} expr2! - - Return the results of multiplication, floating point division, or - remainder of arguments. - - \item \verb!- expr1! - - Return the result of subtracting expr1 from 0. - This, the unary minus operator, is right associative, and - has the same precedence as the ! operator. - - \item \verb+! expr1+ - - Return the result of a logical complement of expr1. - In other words, if expr1 is null, 0, an empty string, - or the string "0", return a 1. Otherwise, return a 0. - It has the same precedence as the unary minus operator, and - is also right associative. - - \item \verb!expr1 : expr2! - - The `:' operator matches expr1 against expr2, which must be a - regular expression. The regular expression is anchored to the - beginning of the string with an implicit `\^'. - - If the match succeeds and the pattern contains at least one regular - expression subexpression `\(...\)', the string corresponing - to `\textbackslash1' is returned; otherwise the matching operator - returns the number of characters matched. If the match fails and - the pattern contains a regular expression subexpression the null - string is returned; otherwise 0. - - Normally, the double quotes wrapping a string are left as part - of the string. This is disastrous to the : operator. Therefore, - before the regex match is made, beginning and ending double quote - characters are stripped from both the pattern and the string. - - \item \verb!expr1 =~ expr2! - - Exactly the same as the ':' operator, except that the match is - not anchored to the beginning of the string. Pardon any similarity - to seemingly similar operators in other programming languages! - The ":" and "=\verb!~!" operators share the same precedence. - - \item \verb!expr1 ? expr2 :: expr3! - - Traditional Conditional operator. If expr1 is a number - that evaluates to 0 (false), expr3 is result of the this - expression evaluation. Otherwise, expr2 is the result. - If expr1 is a string, and evaluates to an empty string, - or the two characters (""), then expr3 is the - result. Otherwise, expr2 is the result. In Asterisk, all - 3 exprs will be "evaluated"; if expr1 is "true", expr2 - will be the result of the "evaluation" of this - expression. expr3 will be the result otherwise. This - operator has the lowest precedence. - - \item \verb!expr1 ~~ expr2! - - Concatenation operator. The two exprs are evaluated and - turned into strings, stripped of surrounding double quotes, - and are turned into a single string with no invtervening spaces. - This operator is new to trunk after 1.6.0; it is not needed - in existing extensions.conf code. Because of the way asterisk - evaluates ${ } and $[ ] constructs (recursively, bottom- - up), no $[] or ${} is ever present when the contents - of a ${} or $[] is evaluated. Thus, tokens are usually - already merged at evaluation time. But, in AEL, various - exprs are evaluated raw, and ${} and $[] are gathered - and treated as tokens. And in AEL, no two tokens can - sit side by side without an intervening operator. - So, in AEL, concatenation must be explicitly specified - in expressions. This new operator will play well into - future plans, where expressions ($[] constructs, and - variable references (${} constructs) are merged into a - single grammar. - -\end{itemize} - -Parentheses are used for grouping in the usual manner. - -Operator precedence is applied as one would expect in any of the C -or C derived languages. - -\subsection{Floating Point Numbers} - -In 1.6 and above, we shifted the \$[...] expressions to be calculated -via floating point numbers instead of integers. We use 'long double' numbers -when possible, which provide around 16 digits of precision with 12 byte numbers. - -To specify a floating point constant, the number has to have this format: D.D, where D is -a string of base 10 digits. So, you can say 0.10, but you can't say .10 or 20.-- we hope -this is not an excessive restriction! - -Floating point numbers are turned into strings via the '\%g'/'\%Lg' format of the printf -function set. This allows numbers to still 'look' like integers to those counting -on integer behavior. If you were counting on 1/4 evaluating to 0, you need to now say -TRUNC(1/4). For a list of all the truncation/rounding capabilities, see the next section. - - -\subsection{Functions} - -In 1.6 and above, we upgraded the \$[] expressions to handle floating point numbers. -Because of this, folks counting on integer behavior would be disrupted. To make -the same results possible, some rounding and integer truncation functions have been -added to the core of the Expr2 parser. Indeed, dialplan functions can be called from -\$[..] expressions without the \$\{...\} operators. The only trouble might be in the fact that -the arguments to these functions must be specified with a comma. If you try to call -the MATH function, for example, and try to say 3 + MATH(7*8), the expression parser will -evaluate 7*8 for you into 56, and the MATH function will most likely complain that its -input doesn't make any sense. - -We also provide access to most of the floating point functions in the C library. (but not all of them). - -While we don't expect someone to want to do Fourier analysis in the dialplan, we -don't want to preclude it, either. - -Here is a list of the 'builtin' functions in Expr2. All other dialplan functions -are available by simply calling them (read-only). In other words, you don't need to -surround function calls in \$[...] expressions with \$\{...\}. Don't jump to conclusions, -though! -- you still need to wrap variable names in curly braces! - -\begin{enumerate} -\item COS(x) x is in radians. Results vary from -1 to 1. -\item SIN(x) x is in radians. Results vary from -1 to 1. -\item TAN(x) x is in radians. -\item ACOS(x) x should be a value between -1 and 1. -\item ASIN(x) x should be a value between -1 and 1. -\item ATAN(x) returns the arc tangent in radians; between -PI/2 and PI/2. -\item ATAN2(x,y) returns a result resembling y/x, except that the signs of both args are used to determine the quadrant of the result. Its result is in radians, between -PI and PI. -\item POW(x,y) returns the value of x raised to the power of y. -\item SQRT(x) returns the square root of x. -\item FLOOR(x) rounds x down to the nearest integer. -\item CEIL(x) rounds x up to the nearest integer. -\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 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. If this quotient is 1/2, it is rounded to the nearest even number. -\item EXP(x) returns e to the x power. -\item EXP2(x) returns 2 to the x power. -\item LOG(x) returns the natural logarithm of x. -\item LOG2(x) returns the base 2 log of x. -\item LOG10(x) returns the base 10 log of x. -\end{enumerate} - -\subsection{Examples} - -\begin{astlisting} -\begin{verbatim} - "One Thousand Five Hundred" =~ "(T[^ ]+)" - returns: Thousand - - "One Thousand Five Hundred" =~ "T[^ ]+" - returns: 8 - - "One Thousand Five Hundred" : "T[^ ]+" - returns: 0 - - "8015551212" : "(...)" - returns: 801 - - "3075551212":"...(...)" - returns: 555 - - ! "One Thousand Five Hundred" =~ "T[^ ]+" - returns: 0 (because it applies to the string, which is non-null, - which it turns to "0", and then looks for the pattern - in the "0", and doesn't find it) - - !( "One Thousand Five Hundred" : "T[^ ]+" ) - returns: 1 (because the string doesn't start with a word starting - with T, so the match evals to 0, and the ! operator - inverts it to 1 ). - - 2 + 8 / 2 - returns 6. (because of operator precedence; the division is done first, then the addition). - - 2+8/2 - returns 6. Spaces aren't necessary. - -(2+8)/2 - returns 5, of course. - -(3+8)/2 - returns 5.5 now. - -TRUNC((3+8)/2) - returns 5. - -FLOOR(2.5) - returns 2 - -FLOOR(-2.5) - returns -3 - -CEIL(2.5) - returns 3. - -CEIL(-2.5) - returns -2. - -ROUND(2.5) - returns 3. - -ROUND(3.5) - returns 4. - -ROUND(-2.5) - returns -3 - -RINT(2.5) - returns 2. - -RINT(3.5) - returns 4. - -RINT(-2.5) - returns -2. - -RINT(-3.5) - returns -4. - -TRUNC(2.5) - returns 2. - -TRUNC(3.5) - returns 3. - -TRUNC(-3.5) - returns -3. -\end{verbatim} -\end{astlisting} - -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 -variable reference \$\{CALLERID(num)\}, for instance. - - -\subsection{Numbers Vs. Strings} - -Tokens consisting only of numbers are converted to 'long double' if possible, which -are from 80 bits to 128 bits depending on the OS, compiler, and hardware. -This means that overflows can occur when the -numbers get above 18 digits (depending on the number of bits involved). Warnings will appear in the logs in this -case. - -\subsection{Conditionals} - -There is one conditional application - the conditional goto : -\begin{astlisting} -\begin{verbatim} - exten => 1,2,GotoIf(condition?label1:label2) -\end{verbatim} -\end{astlisting} - -If condition is true go to label1, else go to label2. Labels are interpreted -exactly as in the normal goto command. - -"condition" is just a string. If the string is empty or "0", the condition -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 -above, eg : - -\begin{astlisting} -\begin{verbatim} - exten => 1,2,GotoIf($[${CALLERID(all)} = 123456]?2,1:3,1) -\end{verbatim} -\end{astlisting} - -Example of use : -\begin{astlisting} -\begin{verbatim} -exten => s,2,Set(vara=1) -exten => s,3,Set(varb=$[${vara} + 2]) -exten => s,4,Set(varc=$[${varb} * 2]) -exten => s,5,GotoIf($[${varc} = 6]?99,1:s,6) -\end{verbatim} -\end{astlisting} - -\subsection{Parse Errors} - -Syntax errors are now output with 3 lines. - -If the extensions.conf file contains a line like: - -\begin{astlisting} -\begin{verbatim} -exten => s,6,GotoIf($[ "${CALLERID(num)}" = "3071234567" & & "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7) -\end{verbatim} -\end{astlisting} - -You may see an error in \path{/var/log/asterisk/messages} like this: -\begin{astlisting} -\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: -"3072312154" = "3071234567" & & "Steves Extension" : "Privacy Manager" - ^ -\end{verbatim} -\end{astlisting} - -The log line tells you that a syntax error was encountered. It now -also tells you (in grand standard bison format) that it hit an "AND" -(\&) token unexpectedly, and that was hoping for for a MINUS (-), LP -(left parenthesis), or a plain token (a string or number). - -The next line shows the evaluated expression, and the line after -that, the position of the parser in the expression when it became confused, -marked with the "\^" character. - -\subsection{NULL Strings} -Testing to see if a string is null can be done in one of two different ways: -\begin{astlisting} -\begin{verbatim} - exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) - or - exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) -\end{verbatim} -\end{astlisting} - -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. - -The first way should work in all cases, and indeed, might now -be the safest way to handle this situation. - -\subsection{Warning} - -If you need to do complicated things with strings, asterisk expressions -is most likely NOT the best way to go about it. AGI scripts are an -excellent option to this need, and make available the full power of -whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java, -Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula, -Pascal, APL, assembler, etc. - -\subsection{Incompatabilities} - -The asterisk expression parser has undergone some evolution. It is hoped -that the changes will be viewed as positive. - -The "original" expression parser had a simple, hand-written scanner, -and a simple bison grammar. This was upgraded to a more involved bison -grammar, and a hand-written scanner upgraded to allow extra spaces, -and to generate better error diagnostics. This upgrade required bison -1.85, and part of the user community felt the pain of having to -upgrade their bison version. - -The next upgrade included new bison and flex input files, and the makefile -was upgraded to detect current version of both flex and bison, conditionally -compiling and linking the new files if the versions of flex and bison would -allow it. - -If you have not touched your extensions.conf files in a year or so, the -above upgrades may cause you some heartburn in certain circumstances, as -several changes have been made, and these will affect asterisk's behavior on -legacy extension.conf constructs. The changes have been engineered -to minimize these conflicts, but there are bound to be problems. - -The following list gives some (and most likely, not all) of areas -of possible concern with "legacy" extension.conf files: - -\begin{enumerate} -\item Tokens separated by space(s). - Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate - to the value '2', but '1+1' would evaluate to the string '1+1'. If this - behavior was depended on, then the expression evaluation will break. '1+1' - will now evaluate to '2', and something is not going to work right. - To keep such strings from being evaluated, simply wrap them in double - quotes: ' "1+1" ' - -\item The colon operator. In versions previous to double quoting, the - colon operator takes the right hand string, and using it as a - regex pattern, looks for it in the left hand string. It is given - an implicit \^ operator at the beginning, meaning the pattern - will match only at the beginning of the left hand string. - If the pattern or the matching string had double quotes around - them, these could get in the way of the pattern match. Now, - the wrapping double quotes are stripped from both the pattern - and the left hand string before applying the pattern. This - was done because it recognized that the new way of - scanning the expression doesn't use spaces to separate tokens, - and the average regex expression is full of operators that - the scanner will recognize as expression operators. Thus, unless - the pattern is wrapped in double quotes, there will be trouble. - For instance, \$\{VAR1\} : (Who$|$What*)+ - may have have worked before, but unless you wrap the pattern - in double quotes now, look out for trouble! This is better: - "\$\{VAR1\}" : "(Who$|$What*)+" - and should work as previous. - -\item Variables and Double Quotes - Before these changes, if a variable's value contained one or more double - quotes, it was no reason for concern. It is now! - -\item LE, GE, NE operators removed. The code supported these operators, - but they were not documented. The symbolic operators, $<$=, $>$=, and != - should be used instead. - -\item Added the unary '-' operator. So you can 3+ -4 and get -1. - -\item Added the unary '!' operator, which is a logical complement. - Basically, if the string or number is null, empty, or '0', - a '1' is returned. Otherwise a '0' is returned. - -\item Added the '=\verb!~!' operator, just in case someone is just looking for - 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. - -\item Added the conditional operator 'expr1 ? true\_expr :: 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. - -\item Unary operators '-' and '!' were made right associative. -\end{enumerate} - -\subsection{Debugging Hints} - -There are two utilities you can build to help debug the \$[ ] in -your extensions.conf file. - -The first, and most simplistic, is to issue the command: -\begin{astlisting} -\begin{verbatim} -make testexpr2 -\end{verbatim} -\end{astlisting} -in the top level asterisk source directory. This will build a small -executable, that is able to take the first command line argument, and -run it thru the expression parser. No variable substitutions will be -performed. It might be safest to wrap the expression in single -quotes... -\begin{astlisting} -\begin{verbatim} -testexpr2 '2*2+2/2' -\end{verbatim} -\end{astlisting} -is an example. - -And, in the utils directory, you can say: -\begin{astlisting} -\begin{verbatim} -make check_expr -\end{verbatim} -\end{astlisting} -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 -have problems when you move to flex-2.5.31. It was originally -designed to help spot possible incompatibilities when moving from the -pre-2.5.31 world to the upgraded version of the lexer. - -But one more capability has been added to check\_expr, that might make -it more generally useful. It now does a simple minded evaluation of -all variables, and then passes the \$[] exprs to the parser. If there -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 -extensions.conf file, to see if they pass a crude syntax check. - -The "simple-minded" variable substitution replaces \$\{varname\} variable -references with '555'. You can override the 555 for variable values, -by entering in var=val arguments after the filename on the command -line. So... -\begin{astlisting} -\begin{verbatim} - check_expr /etc/asterisk/extensions.conf CALLERID(num)=3075551212 DIALSTATUS=TORTURE EXTEN=121 -\end{verbatim} -\end{astlisting} -will substitute any \$\{CALLERID(num)\} variable references with -3075551212, any \$\{DIALSTATUS\} variable references with 'TORTURE', and -any \$\{EXTEN\} references with '121'. If there is any fancy stuff -going on in the reference, like \$\{EXTEN:2\}, then the override will -not work. Everything in the \$\{...\} has to match. So, to substitute -\$\{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: - -\begin{astlisting} -\begin{verbatim} - OK -- $[ "${DIALSTATUS}" = "TORTURE" | "${DIALSTATUS}" = "DONTCALL" ] at line 416 -\end{verbatim} -\end{astlisting} - -In the expr2\_log file that is generated, you will see: - -\begin{astlisting} -\begin{verbatim} - line 416, evaluation of $[ "TORTURE" = "TORTURE" | "TORTURE" = "DONTCALL" ] result: 1 -\end{verbatim} -\end{astlisting} - -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 -useful. - -\section{Asterisk standard channel variables} - -There are a number of variables that are defined or read -by Asterisk. Here is a list of them. More information is -available in each application's help text. All these variables -are in UPPER CASE only. - -Variables marked with a * are builtin functions and can't be set, -only read in the dialplan. Writes to such variables are silently -ignored. - -\begin{verbatim} -${CDR(accountcode)} * Account code (if specified) -${BLINDTRANSFER} The name of the channel on the other side of a blind transfer -${BRIDGEPEER} Bridged peer -${BRIDGEPVTCALLID} Bridged peer PVT call ID (SIP Call ID if a SIP call) -${CALLERID(ani)} * Caller ANI (PRI channels) -${CALLERID(ani2)} * ANI2 (Info digits) also called Originating line information or OLI -${CALLERID(all)} * Caller ID -${CALLERID(dnid)} * Dialed Number Identifier -${CALLERID(name)} * Caller ID Name only -${CALLERID(num)} * Caller ID Number only -${CALLERID(rdnis)} * Redirected Dial Number ID Service -${CALLINGANI2} * Caller ANI2 (PRI channels) -${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels) -${CALLINGTNS} * Transit Network Selector (PRI channels) -${CALLINGTON} * Caller Type of Number (PRI channels) -${CHANNEL} * Current channel name -${CONTEXT} * Current context -${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS - (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)}) -${DB_RESULT} Result value of DB_EXISTS() dial plan function -${EPOCH} * Current unix style epoch -${EXTEN} * Current extension -${ENV(VAR)} Environmental variable VAR -${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority - after a blind transfer (use ^ characters in place of - | to separate context/extension/priority when setting - this variable from the dialplan) -${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound) -${HINT} * Channel hints for this extension -${HINTNAME} * Suggested Caller*ID name for this extension -${INVALID_EXTEN} The invalid called extension (used in the "i" extension) -${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()}) -${LEN(VAR)} * String length of VAR (integer) -${PRIORITY} * Current priority in the dialplan -${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed -${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS - (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}) -${TRANSFER_CONTEXT} Context for transferred calls -${FORWARD_CONTEXT} Context for forwarded calls -${DYNAMIC_PEERNAME} The name of the channel on the other side when a dynamic - feature is used. -${DYNAMIC_FEATURENAME} The name of the last triggered dynamic feature. -${UNIQUEID} * Current call unique identifier -${SYSTEMNAME} * value of the systemname option of asterisk.conf -${ENTITYID} * Global Entity ID set automatically, or from asterisk.conf -\end{verbatim} - -\subsection{Application return values} - -Many applications return the result in a variable that you read to -get the result of the application. These status fields are unique -for each application. -For the various status values, see each application's help text. -\begin{verbatim} -${AGISTATUS} * agi() -${AQMSTATUS} * addqueuemember() -${AVAILSTATUS} * chanisavail() -${CHECKGROUPSTATUS} * checkgroup() -${CHECKMD5STATUS} * checkmd5() -${CPLAYBACKSTATUS} * controlplayback() -${DIALSTATUS} * dial() -${DBGETSTATUS} * dbget() -${ENUMSTATUS} * enumlookup() -${HASVMSTATUS} * hasnewvoicemail() -${LOOKUPBLSTATUS} * lookupblacklist() -${OSPAUTHSTATUS} * ospauth() -${OSPLOOKUPSTATUS} * osplookup() -${OSPNEXTSTATUS} * ospnext() -${OSPFINISHSTATUS} * ospfinish() -${PARKEDAT} * parkandannounce() -${PLAYBACKSTATUS} * playback() -${PQMSTATUS} * pausequeuemember() -${PRIVACYMGRSTATUS} * privacymanager() -${QUEUESTATUS} * queue() -${RQMSTATUS} * removequeuemember() -${SENDIMAGESTATUS} * sendimage() -${SENDTEXTSTATUS} * sendtext() -${SENDURLSTATUS} * sendurl() -${SYSTEMSTATUS} * system() -${TRANSFERSTATUS} * transfer() -${TXTCIDNAMESTATUS} * txtcidname() -${UPQMSTATUS} * unpausequeuemember() -${VMSTATUS} * voicmail() -${VMBOXEXISTSSTATUS} * vmboxexists() -${WAITSTATUS} * waitforsilence() -\end{verbatim} - -\subsection{Various application variables} -\begin{verbatim} -${CURL} * Resulting page content for curl() -${ENUM} * Result of application EnumLookup -${EXITCONTEXT} Context to exit to in IVR menu (app background()) - or in the RetryDial() application -${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor()) -${MONITOR_EXEC} Application to execute after monitoring a call -${MONITOR_EXEC_ARGS} Arguments to application -${MONITOR_FILENAME} File for monitoring (recording) calls in queue -${QUEUE_PRIO} Queue priority -${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller -${QUEUE_MIN_PENALTY} Minimum member penalty allowed to answer caller -${QUEUESTATUS} Status of the call, one of: - (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL) -${QUEUEPOSITION} * When a caller is removed from a queue, his current position is logged - in this variable. If the value is 0, then this means that the caller was - serviced by a queue member. If non-zero, then this was the position in the - queue the caller was in when he left. -${RECORDED_FILE} * Recorded file in record() -${TALK_DETECTED} * Result from talkdetect() -${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record) -${TOUCH_MONITOR_PREF} * The prefix for automonitor recording filenames. -${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record) -${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record) -${TOUCH_MONITOR_MESSAGE_START} Recorded file to play for both channels at start of monitoring session -${TOUCH_MONITOR_MESSAGE_STOP} Recorded file to play for both channels at end of monitoring session -${TXTCIDNAME} * Result of application TXTCIDName -${VPB_GETDTMF} chan_vpb -\end{verbatim} - -\subsection{The MeetMe Conference Bridge} -\begin{verbatim} -${MEETME_RECORDINGFILE} Name of file for recording a conference with - the "r" option -${MEETME_RECORDINGFORMAT} Format of file to be recorded -${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting -${MEETME_AGI_BACKGROUND} AGI script for Meetme (DAHDI only) -${MEETMESECS} * Number of seconds a user participated in a MeetMe conference -${CONF_LIMIT_TIMEOUT_FILE} File to play when time is up. Used with the L() option. -${CONF_LIMIT_WARNING_FILE} File to play as warning if 'y' is defined. - The default is to say the time remaining. Used with the L() option. -${MEETMEBOOKID} * This variable exposes the bookid column for a realtime configured conference bridge. -\end{verbatim} - -\subsection{The VoiceMail() application} -\begin{verbatim} -${VM_CATEGORY} Sets voicemail category -${VM_NAME} * Full name in voicemail -${VM_DUR} * Voicemail duration -${VM_MSGNUM} * Number of voicemail message in mailbox -${VM_CALLERID} * Voicemail Caller ID (Person leaving vm) -${VM_CIDNAME} * Voicemail Caller ID Name -${VM_CIDNUM} * Voicemail Caller ID Number -${VM_DATE} * Voicemail Date -${VM_MESSAGEFILE} * Path to message left by caller -\end{verbatim} - -\subsection{The VMAuthenticate() application} -\begin{verbatim} -${AUTH_MAILBOX} * Authenticated mailbox -${AUTH_CONTEXT} * Authenticated mailbox context -\end{verbatim} - -\subsection{DUNDiLookup()} -\begin{verbatim} -${DUNDTECH} * The Technology of the result from a call to DUNDiLookup() -${DUNDDEST} * The Destination of the result from a call to DUNDiLookup() -\end{verbatim} - -\subsection{chan\_dahdi} -\begin{verbatim} -${ANI2} * The ANI2 Code provided by the network on the incoming call. - (ie, Code 29 identifies call as a Prison/Inmate Call) -${CALLTYPE} * Type of call (Speech, Digital, etc) -${CALLEDTON} * Type of number for incoming PRI extension - i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, - 4=subscriber, 6=abbreviated, 7=reserved -${CALLINGSUBADDR} * Caller's PRI Subaddress -${FAXEXTEN} * The extension called before being redirected to "fax" -${PRIREDIRECTREASON} * Reason for redirect, if a call was directed -${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type' - of message 'b' or 'u' -\end{verbatim} - -\subsection{chan\_sip} -\begin{verbatim} -${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching) -${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate) -${SIPFROMDOMAIN} Set SIP domain on outbound calls -${SIPUSERAGENT} * SIP user agent (deprecated) -${SIPURI} * SIP uri -${SIP_MAX_FORWARDS} Set the value of the Max-Forwards header for outbound call -${SIP_CODEC} Set the SIP codec for an inbound call -${SIP_CODEC_INBOUND} Set the SIP codec for an inbound call -${SIP_CODEC_OUTBOUND} Set the SIP codec for an outbound call -${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call -${RTPAUDIOQOS} RTCP QoS report for the audio of this call -${RTPVIDEOQOS} RTCP QoS report for the video of this call -\end{verbatim} - -\subsection{chan\_agent} -\begin{verbatim} -${AGENTMAXLOGINTRIES} Set the maximum number of failed logins -${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data -${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out -${AGENTACKCALL} Whether the agent should acknowledge the incoming call -${AGENTAUTOLOGOFF} Auto logging off for an agent -${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls -${AGENTNUMBER} * Agent number (username) set at login -${AGENTSTATUS} * Status of login ( fail | on | off ) -${AGENTEXTEN} * Extension for logged in agent -\end{verbatim} - - -\subsection{The Dial() application} -\begin{verbatim} -${DIALEDPEERNAME} * Dialed peer name -${DIALEDPEERNUMBER} * Dialed peer number -${DIALEDTIME} * Time for the call (seconds). Is only set if call was answered. -${ANSWEREDTIME} * Time from answer to hangup (seconds) -${DIALSTATUS} * Status of the call, one of: - (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER - | ANSWER | CANCEL | DONTCALL | TORTURE) -${DYNAMIC_FEATURES} * The list of features (from the [applicationmap] section of - features.conf) to activate during the call, with feature - names separated by '#' characters -${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits -${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits -${LIMIT_WARNING_FILE} Soundfile for call limits -${LIMIT_TIMEOUT_FILE} Soundfile for call limits -${LIMIT_CONNECT_FILE} Soundfile for call limits -${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup) - * See "show application dial" for more information -\end{verbatim} - -\subsection{The chanisavail() application} -\begin{verbatim} -${AVAILCHAN} * the name of the available channel if one was found -${AVAILORIGCHAN} * the canonical channel name that was used to create the channel -${AVAILSTATUS} * Status of requested channel -\end{verbatim} - -\subsection{Dialplan Macros} -\begin{verbatim} -${MACRO_EXTEN} * The calling extensions -${MACRO_CONTEXT} * The calling context -${MACRO_PRIORITY} * The calling priority -${MACRO_OFFSET} Offset to add to priority at return from macro -\end{verbatim} - -\subsection{The ChanSpy() application} -\begin{verbatim} -${SPYGROUP} * A ':' (colon) separated list of group names. - (To be set on spied on channel and matched against the g(grp) option) -\end{verbatim} - -\subsection{OSP} -\begin{verbatim} -${OSPINHANDLE} The inbound call OSP transaction handle. -${OSPINTOKEN} The inbound OSP token. -${OSPINTIMELIMIT} The inbound call duration limit in seconds. -${OSPINPEERIP} The last hop IP address. -${OSPINNETWORKID} The inbound source network ID. -${OSPINNPRN} The inbound routing number. -${OSPINNPCIC} The inbound carrier identification code. -${OSPINNPDI} The inbound number portability database dip indicator. -${OSPINSPID} The inbound service provider identity. -${OSPINOCN} The inbound operator company number. -${OSPINSPN} The inbound service provider name. -${OSPINALTSPN} The inbound alternate service provider name. -${OSPINMCC} The inbound mobile country code. -${OSPINMNC} The inbound mobile network code. -${OSPINDIVUSER} The inbound Diversion header user part. -${OSPINDIVHOST} The inbound Diversion header host part. -${OSPINTOHOST} The inbound To header host part. -${OSPINCUSTOMINFOn} The inbound custom information. - Where n is the index beginning with 1 upto 8. -${OSPOUTHANDLE} The outbound call OSP transaction handle. -${OSPOUTTOKEN} The outbound OSP token. -${OSPOUTTIMELIMIT} The outbound call duration limit in seconds. -${OSPOUTTECH} The outbound channel technology. -${OSPOUTCALLIDTYPES} The outbound Call-ID types. -${OSPOUTCALLID} The outbound Call-ID. Only for H.323. -${OSPDESTINATION} The destination IP address. -${OSPDESTREMAILS} The number of remained destinations. -${OSPOUTCALLING} The outbound calling number. -${OSPOUTCALLED} The outbound called number. -${OSPOUTNETWORKID} The outbound destination network ID. -${OSPOUTNPRN} The outbound routing number. -${OSPOUTNPCIC} The outbound carrier identification code. -${OSPOUTNPDI} The outbound number portability database dip indicator. -${OSPOUTSPID} The outbound service provider identity. -${OSPOUTOCN} The outbound operator company number. -${OSPOUTSPN} The outbound service provider name. -${OSPOUTALTSPN} The outbound alternate service provider name. -${OSPOUTMCC} The outbound mobile country code. -${OSPOUTMNC} The outbound mobile network code. -${OSPDIALSTR} The outbound Dial command string. -${OSPINAUDIOQOS} The inbound call leg audio QoS string. -${OSPOUTAUDIOQOS} The outbound call leg audio QoS string. -\end{verbatim} - -\subsection{Digit manipulation} -\begin{verbatim} -${REDIRECTING_CALLEE_SEND_MACRO} - Macro to call before sending a redirecting update to the callee -${REDIRECTING_CALLEE_SEND_MACRO_ARGS} - Arguments to pass to ${REDIRECTING_CALLEE_SEND_MACRO} -${REDIRECTING_CALLER_SEND_MACRO} - Macro to call before sending a redirecting update to the caller -${REDIRECTING_CALLER_SEND_MACRO_ARGS} - Arguments to pass to ${REDIRECTING_CALLER_SEND_MACRO} - -${CONNECTED_LINE_CALLEE_SEND_MACRO} - Macro to call before sending a connected line update to the callee -${CONNECTED_LINE_CALLEE_SEND_MACRO_ARGS} - Arguments to pass to ${CONNECTED_LINE_CALLEE_SEND_MACRO} -${CONNECTED_LINE_CALLER_SEND_MACRO} - Macro to call before sending a connected line update to the caller -${CONNECTED_LINE_CALLER_SEND_MACRO_ARGS} - Arguments to pass to ${CONNECTED_LINE_CALLER_SEND_MACRO} -\end{verbatim} |