* Move LaTeX docs into a tex/ subdirectory of the doc/ dir
[asterisk/asterisk.git] / doc / tex / channelvariables.tex
1 \section{Introduction}
2
3 There are two levels of parameter evaluation done in the Asterisk
4 dial plan in extensions.conf.
5 \begin{enumerate}
6 \item The first, and most frequently used, is the substitution of variable
7   references with their values. 
8 \item Then there are the evaluations of expressions done in \$[ .. ]. 
9   This will be discussed below.
10 \end{enumerate}
11 Asterisk has user-defined variables and standard variables set
12 by various modules in Asterisk. These standard variables are
13 listed at the end of this document.
14
15 \section{Parameter Quoting}
16 \begin{verbatim}
17 exten => s,5,BackGround,blabla
18 \end{verbatim}
19 The parameter (blabla) can be quoted ("blabla"). In this case, a 
20 comma does not terminate the field. However, the double quotes
21 will be passed down to the Background command, in this example.
22
23 Also, characters special to variable substitution, expression evaluation, etc
24 (see below), can be quoted. For example, to literally use a \$ on the 
25 string "\$1231", quote it with a preceding \\. Special characters that must
26 be quoted to be used, are [ ] \$ " \\. (to write \\ itself, use \\). 
27
28 These Double quotes and escapes are evaluated at the level of the
29 asterisk config file parser. 
30
31 Double quotes can also be used inside expressions, as discussed below.
32
33 \section{Variables}
34
35 Parameter strings can include variables. Variable names are arbitrary strings. 
36 They are stored in the respective channel structure. 
37
38 To set a variable to a particular value, do : 
39 \begin{verbatim}
40     exten => 1,2,Set(varname=value)
41 \end{verbatim}
42 You can substitute the value of a variable everywhere using \${variablename}.
43 For example, to stringwise append \$lala to \$blabla and store result in \$koko, 
44 do: 
45 \begin{verbatim}
46    exten => 1,2,Set(koko=${blabla}${lala})
47 \end{verbatim}
48
49 There are two reference modes - reference by value and reference by name. 
50 To refer to a variable with its name (as an argument to a function that 
51 requires a variable), just write the name. To refer to the variable's value, 
52 enclose it inside \${}. For example, Set takes as the first argument 
53 (before the =) a variable name, so: 
54 \begin{verbatim}
55         exten => 1,2,Set(koko=lala)
56         exten => 1,3,Set(${koko}=blabla)
57 \end{verbatim}
58 stores to the variable "koko" the value "lala" and to variable "lala" the 
59 value "blabla". 
60
61 In fact, everything contained \${here} is just replaced with the value of 
62 the variable "here". 
63
64 \section{Variable Inheritance}
65
66 Variable names which are prefixed by "\_" will be inherited to channels 
67 that are created in the process of servicing the original channel in 
68 which the variable was set.  When the inheritance takes place, the 
69 prefix will be removed in the channel inheriting the variable.  If the 
70 name is prefixed by "\_\_" in the channel, then the variable is 
71 inherited and the "\_\_" will remain intact in the new channel.
72
73 In the dialplan, all references to these variables refer to the same 
74 variable, regardless of having a prefix or not.  Note that setting any 
75 version of the variable removes any other version of the variable, 
76 regardless of prefix.
77
78 \subsection{Example}
79 \begin{verbatim}
80 Set(__FOO=bar) ; Sets an inherited version of "FOO" variable 
81 Set(FOO=bar)   ; Removes the inherited version and sets a local 
82                ; variable.
83
84 However,
85
86 NoOp(${__FOO}) is identical to NoOp(${FOO})
87 \end{verbatim}
88
89
90 \section{Selecting Characters from Variables}
91
92 The format for selecting characters from a variable can be expressed as:
93 \begin{verbatim}
94         ${variable_name[:offset[:length]]}
95 \end{verbatim}
96 If you want to select the first N characters from the string assigned
97 to a variable, simply append a colon and the number of characters to
98 skip from the beginning of the string to the variable name.
99 \begin{verbatim}
100         ;Remove the first character of extension, save in "number" variable
101         exten => _9X.,1,Set(number=${EXTEN:1})
102 \end{verbatim}
103 Assuming we've dialed 918005551234, the value saved to the 'number' variable
104 would be 18005551234. This is useful in situations when we require users to 
105 dial a number to access an outside line, but do not wish to pass the first 
106 digit.
107
108 If you use a negative offset number, Asterisk starts counting from the end 
109 of the string and then selects everything after the new position. The following
110 example will save the numbers 1234 to the 'number' variable, still assuming
111 we've dialed 918005551234.
112 \begin{verbatim}
113         ;Remove everything before the last four digits of the dialed string
114         exten => _9X.,1,Set(number=${EXTEN:-4})
115 \end{verbatim}
116 We can also limit the number of characters from our offset position that we
117 wish to use. This is done by appending a second colon and length value to the
118 variable name. The following example will save the numbers 555 to the 'number'
119 variable.
120 \begin{verbatim}
121         ;Only save the middle numbers 555 from the string 918005551234
122         exten => _9X.,1,Set(number=${EXTEN:5:3})
123 \end{verbatim}
124 The length value can also be used in conjunction with a negative offset. This
125 may be useful if the length of the string is unknown, but the trailing digits
126 are. The following example will save the numbers 555 to the 'number' variable,
127 even if the string starts with more characters than expected (unlike the
128 previous example).
129 \begin{verbatim}
130         ;Save the numbers 555 to the 'number' variable
131         exten => _9X.,1,Set(number=${EXTEN:-7:3})
132 \end{verbatim}
133 If a negative length value is entered, Asterisk will remove that many characters
134 from the end of the string.
135 \begin{verbatim}
136         ;Set pin to everything but the trailing #.
137         exten => _XXXX#,1,Set(pin=${EXTEN:0:-1})
138 \end{verbatim}
139
140 \section{Expressions} 
141
142 Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is 
143 considered as an expression and it is evaluated. Evaluation works similar to 
144 (but is done on a later stage than) variable substitution: the expression 
145 (including the square brackets) is replaced by the result of the expression 
146 evaluation. 
147
148 For example, after the sequence:
149 \begin{verbatim}
150 exten => 1,1,Set(lala=$[1 + 2])
151 exten => 1,2,Set(koko=$[2 * ${lala}])
152 \end{verbatim}
153 the value of variable koko is "6".
154
155 and, further:
156 \begin{verbatim}
157 exten => 1,1,Set,(lala=$[  1 +    2   ]);
158 \end{verbatim}
159 will parse as intended. Extra spaces are ignored.
160
161
162 \subsection{Spaces Inside Variables Values}
163
164 If the variable being evaluated contains spaces, there can be problems.
165
166 For these cases, double quotes around text that may contain spaces
167 will force the surrounded text to be evaluated as a single token.
168 The double quotes will be counted as part of that lexical token.
169
170 As an example:
171
172 \begin{verbatim}
173 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
174 \end{verbatim}
175
176 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
177 but the above will evaluate to:
178
179 \begin{verbatim}
180 "DELOREAN MOTORS" : "Privacy Manager"
181 \end{verbatim}
182
183 and will evaluate to 0.
184
185 The above without double quotes would have evaluated to:
186
187 \begin{verbatim}
188 DELOREAN MOTORS : Privacy Manager
189 \end{verbatim}
190
191 and will result in syntax errors, because token DELOREAN is immediately
192 followed by token MOTORS and the expression parser will not know how to 
193 evaluate this expression, because it does not match its grammar.
194
195 \subsection{Operators}
196
197 Operators are listed below in order of increasing precedence.  Operators
198 with equal precedence are grouped within { } symbols.
199
200 \begin{verbatim}
201      expr1 | expr2
202              Return the evaluation of expr1 if it is neither an empty string
203              nor zero; otherwise, returns the evaluation of expr2.
204
205      expr1 & expr2
206              Return the evaluation of expr1 if neither expression evaluates to
207              an empty string or zero; otherwise, returns zero.
208
209      expr1 {=, >, >=, <, <=, !=} expr2
210              Return the results of integer comparison if both arguments are
211              integers; otherwise, returns the results of string comparison
212              using the locale-specific collation sequence.  The result of each
213              comparison is 1 if the specified relation is true, or 0 if the
214              relation is false.
215
216      expr1 {+, -} expr2
217              Return the results of addition or subtraction of integer-valued
218              arguments.
219
220      expr1 {*, /, %} expr2
221              Return the results of multiplication, integer division, or
222              remainder of integer-valued arguments.
223
224      - expr1
225             Return the result of subtracting expr1 from 0.
226             This, the unary minus operator, is right associative, and
227             has the same precedence as the ! operator.
228
229      ! expr1
230             Return the result of a logical complement of expr1.
231             In other words, if expr1 is null, 0, an empty string,
232             or the string "0", return a 1. Otherwise, return a 0.
233             It has the same precedence as the unary minus operator, and
234             is also right associative.
235
236      expr1 : expr2
237              The `:' operator matches expr1 against expr2, which must be a
238              regular expression.  The regular expression is anchored to the
239              beginning of  the string with an implicit `^'.
240
241              If the match succeeds and the pattern contains at least one regu-
242              lar expression subexpression `\(...\)', the string correspond-
243              ing to `\1' is returned; otherwise the matching operator
244              returns the number of characters matched.  If the match fails and
245              the pattern contains a regular expression subexpression the null
246              string is returned; otherwise 0.
247
248              Normally, the double quotes wrapping a string are left as part
249              of the string. This is disastrous to the : operator. Therefore,
250              before the regex match is made, beginning and ending double quote
251              characters are stripped from both the pattern and the string.
252
253       expr1 =~ expr2
254              Exactly the same as the ':' operator, except that the match is
255              not anchored to the beginning of the string. Pardon any similarity
256              to seemingly similar operators in other programming languages!
257              The ":" and "=~" operators share the same precedence.
258
259       expr1 ? expr2 :: expr3
260              Traditional Conditional operator. If expr1 is a number
261              that evaluates to 0 (false), expr3 is result of the this
262              expression evaluation.  Otherwise, expr2 is the result.
263              If expr1 is a string, and evaluates to an empty string,
264              or the two characters (""), then expr3 is the
265              result. Otherwise, expr2 is the result.  In Asterisk, all
266              3 exprs will be "evaluated"; if expr1 is "true", expr2
267              will be the result of the "evaluation" of this
268              expression.  expr3 will be the result otherwise. This
269              operator has the lowest precedence.
270 \end{verbatim}
271
272 Parentheses are used for grouping in the usual manner.
273
274 Operator precedence is applied as one would expect in any of the C
275 or C derived languages.
276
277 \subsection{Examples}
278
279 \begin{verbatim}
280  "One Thousand Five Hundred" =~ "(T[^ ]+)"
281         returns: Thousand
282
283  "One Thousand Five Hundred" =~ "T[^ ]+"
284         returns: 8
285
286  "One Thousand Five Hundred" : "T[^ ]+"
287         returns: 0
288
289  "8015551212" : "(...)"
290         returns: 801
291
292  "3075551212":"...(...)"
293         returns: 555
294
295  ! "One Thousand Five Hundred" =~ "T[^ ]+"
296         returns: 0 (because it applies to the string, which is non-null,
297                     which it turns to "0", and then looks for the pattern
298                     in the "0", and doesn't find it)
299
300  !( "One Thousand Five Hundred" : "T[^ ]+" )
301         returns: 1  (because the string doesn't start with a word starting
302                      with T, so the match evals to 0, and the ! operator
303                      inverts it to 1 ).
304
305  2 + 8 / 2
306         returns 6. (because of operator precedence; the division is done first, then the addition).
307
308  2+8/2
309         returns 6. Spaces aren't necessary.
310
311 (2+8)/2
312         returns 5, of course.
313 \begin{verbatim}
314
315 Of course, all of the above examples use constants, but would work the
316 same if any of the numeric or string constants were replaced with a
317 variable reference \${CALLERIDNUM}, for instance.
318
319
320 \subsection{Numbers Vs. Strings}
321
322 Tokens consisting only of numbers are converted to 64-bit numbers for
323 most of the operators. This means that overflows can occur when the
324 numbers get above 18 digits.  Warnings will appear in the logs in this
325 case.
326
327 \subsection{Conditionals}
328
329 There is one conditional application - the conditional goto : 
330
331 \begin{verbatim}
332         exten => 1,2,gotoif(condition?label1:label2)
333 \end{verbatim}
334
335 If condition is true go to label1, else go to label2. Labels are interpreted
336 exactly as in the normal goto command.
337
338 "condition" is just a string. If the string is empty or "0", the condition
339 is considered to be false, if it's anything else, the condition is true. 
340 This is designed to be used together with the expression syntax described 
341 above, eg : 
342
343 \begin{verbatim}
344         exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
345 \end{verbatim}
346
347 Example of use : 
348
349 \begin{verbatim}
350 exten => s,2,Set(vara=1)
351 exten => s,3,Set(varb=$[${vara} + 2])
352 exten => s,4,Set(varc=$[${varb} * 2])
353 exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
354 \end{verbatim}
355
356 \subsection{Parse Errors}
357
358 Syntax errors are now output with 3 lines.
359
360 If the extensions.conf file contains a line like:
361
362 \begin{verbatim}
363 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & &  "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
364 \end{verbatim}
365
366 You may see an error in /var/log/asterisk/messages like this:
367 \begin{verbatim}
368 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:
369 "3072312154"  = "3071234567" & & "Steves Extension" : "Privacy Manager" 
370                                ^
371 \end{verbatim}
372
373 The log line tells you that a syntax error was encountered. It now
374 also tells you (in grand standard bison format) that it hit an "AND"
375 (\&) token unexpectedly, and that was hoping for for a MINUS (-), LP
376 (left parenthesis), or a plain token (a string or number).
377
378 The next line shows the evaluated expression, and the line after
379 that, the position of the parser in the expression when it became confused,
380 marked with the "\^" character.
381
382 \subsection{NULL Strings}
383 Testing to see if a string is null can be done in one of two different ways:
384 \begin{verbatim}
385         exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
386
387         exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
388 \end{verbatim}
389
390 The second example above is the way suggested by the WIKI. It will 
391 work as long as there are no spaces in the evaluated value.
392
393 The first way should work in all cases, and indeed, might now
394 be the safest way to handle this situation.
395
396 \subsection{Warning}
397
398 If you need to do complicated things with strings, asterisk expressions
399 is most likely NOT the best way to go about it. AGI scripts are an
400 excellent option to this need, and make available the full power of
401 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
402 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
403 Pascal, APL, assembler, etc.
404
405 \subsection{Incompatabilities}
406
407 The asterisk expression parser has undergone some evolution. It is hoped
408 that the changes will be viewed as positive. 
409
410 The "original" expression parser had a simple, hand-written scanner,
411 and a simple bison grammar. This was upgraded to a more involved bison
412 grammar, and a hand-written scanner upgraded to allow extra spaces,
413 and to generate better error diagnostics. This upgrade required bison
414 1.85, and part of the user community felt the pain of having to
415 upgrade their bison version.
416
417 The next upgrade included new bison and flex input files, and the makefile
418 was upgraded to detect current version of both flex and bison, conditionally
419 compiling and linking the new files if the versions of flex and bison would
420 allow it.
421
422 If you have not touched your extensions.conf files in a year or so, the
423 above upgrades may cause you some heartburn in certain circumstances, as
424 several changes have been made, and these will affect asterisk's behavior on 
425 legacy extension.conf constructs.  The changes have been engineered
426 to minimize these conflicts, but there are bound to be problems.
427
428 The following list gives some (and most likely, not all) of areas
429 of possible concern with "legacy" extension.conf files:
430
431 \begin{enumerate}
432 \item Tokens separated by space(s).
433    Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate
434    to the value '2', but '1+1' would evaluate to the string '1+1'. If this
435    behavior was depended on, then the expression evaluation will break. '1+1'
436    will now evaluate to '2', and something is not going to work right.
437    To keep such strings from being evaluated, simply wrap them in double 
438    quotes: '  "1+1" '
439
440 \item The colon operator. In versions previous to double quoting, the
441    colon operator takes the right hand string, and using it as a 
442    regex pattern, looks for it in the left hand string. It is given
443    an implicit \^ operator at the beginning, meaning the pattern 
444    will match only at the beginning of the left hand string. 
445    If the pattern or the matching string had double quotes around
446    them, these could get in the way of the pattern match. Now,
447    the wrapping double quotes are stripped from both the pattern 
448    and the left hand string before applying the pattern. This
449    was done because it recognized that the new way of
450    scanning the expression doesn't use spaces to separate tokens,
451    and the average regex expression is full of operators that 
452    the scanner will recognize as expression operators. Thus, unless
453    the pattern is wrapped in double quotes, there will be trouble.
454    For instance,      \${VAR1} : (Who|What*)+
455    may have have worked before, but unless you wrap the pattern
456    in double quotes now, look out for trouble! This is better:
457          "\${VAR1}" : "(Who|What*)+"
458    and should work as previous.
459
460 \item Variables and Double Quotes
461    Before these changes, if a variable's value contained one or more double
462    quotes, it was no reason for concern. It is now!
463
464 \item LE, GE, NE operators removed. The code supported these operators,
465    but they were not documented. The symbolic operators, <=, >=, and !=
466    should be used instead.
467
468 \item  Added the unary '-' operator. So you can 3+ -4 and get -1.
469
470 \item  Added the unary '!' operator, which is a logical complement.
471     Basically, if the string or number is null, empty, or '0',
472     a '1' is returned. Otherwise a '0' is returned.
473
474 \item  Added the '=~' operator, just in case someone is just looking for
475     match anywhere in the string. The only diff with the ':' is that
476     match doesn't have to be anchored to the beginning of the string.
477
478 \item  Added the conditional operator  'expr1 ? true\_expr :: false\_expr'
479     First, all 3 exprs are evaluated, and if expr1 is false, the 'false\_expr'
480     is returned as the result. See above for details. 
481
482 \item  Unary operators '-' and '!' were made right associative.
483 \end{enumerate}
484
485 \subsection{Debugging Hints}
486
487 There are two utilities you can build to help debug the \$[ ] in
488 your extensions.conf file.
489
490 The first, and most simplistic, is to issue the command:
491
492 make testexpr2
493
494 in the top level asterisk source directory. This will build a small
495 executable, that is able to take the first command line argument, and
496 run it thru the expression parser. No variable substitutions will be
497 performed. It might be safest to wrap the expression in single
498 quotes...
499
500 testexpr2 '2*2+2/2'
501
502 is an example.
503
504 And, in the utils directory, you can say:
505
506 make check\_expr
507
508 and a small program will be built, that will check the file mentioned
509 in the first command line argument, for any expressions that might be
510 have problems when you move to flex-2.5.31.  It was originally
511 designed to help spot possible incompatibilities when moving from the
512 pre-2.5.31 world to the upgraded version of the lexer.
513
514 But one more capability has been added to check\_expr, that might make
515 it more generally useful. It now does a simple minded evaluation of
516 all variables, and then passes the \$[] exprs to the parser. If there
517 are any parse errors, they will be reported in the log file. You can
518 use check\_expr to do a quick sanity check of the expressions in your
519 extensions.conf file, to see if they pass a crude syntax check.
520
521 The "simple-minded" variable substitution replaces \${varname} variable
522 references with '555'. You can override the 555 for variable values,
523 by entering in var=val arguments after the filename on the command
524 line.  So...
525
526  check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN=121
527
528 will substitute any \${CALLERIDNUM} variable references with
529 3075551212, any \${DIALSTATUS} variable references with 'TORTURE', and
530 any \${EXTEN} references with '121'.  If there is any fancy stuff
531 going on in the reference, like \${EXTEN:2}, then the override will
532 not work. Everything in the \${...} has to match. So, to substitute
533 \${EXTEN:2} references, you'd best say:
534
535  check\_expr /etc/asterisk/extensions.conf CALLERIDNUM=3075551212 DIALSTATUS=TORTURE EXTEN:2=121
536
537 on stdout, you will see something like:
538
539  OK -- \$[ "\${DIALSTATUS}"  = "TORTURE" | "\${DIALSTATUS}" = "DONTCALL" ] at line 416
540
541 In the expr2\_log file that is generated, you will see:
542
543  line 416, evaluation of \$[  "TORTURE"  = "TORTURE" | "TORTURE" = "DONTCALL"  ] result: 1
544
545 check\_expr is a very simplistic algorithm, and it is far from being
546 guaranteed to work in all cases, but it is hoped that it will be
547 useful.
548
549 \section{Asterisk standard channel variables}
550
551 There are a number of variables that are defined or read
552 by Asterisk. Here is a list of them. More information is
553 available in each application's help text. All these variables
554 are in UPPER CASE only.
555
556 Variables marked with a * are builtin functions and can't be set,
557 only read in the dialplan.  Writes to such variables are silently 
558 ignored.
559
560 \begin{verbatim}
561 ${ACCOUNTCODE}          * Account code (if specified) (Deprecated; use ${CDR(accountcode)})
562 ${BLINDTRANSFER}        The name of the channel on the other side of a blind transfer
563 ${BRIDGEPEER}           Bridged peer
564 ${CALLERANI}            * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)})
565 ${CALLERID}             * Caller ID (Deprecated; use ${CALLERID(all)})
566 ${CALLERIDNAME}         * Caller ID Name only (Deprecated; use ${CALLERID(name)})
567 ${CALLERIDNUM}          * Caller ID Number only (Deprecated; use ${CALLERID(num)})
568 ${CALLINGANI2}          * Caller ANI2 (PRI channels)
569 ${CALLINGPRES}          * Caller ID presentation for incoming calls (PRI channels)
570 ${CALLINGTNS}           * Transit Network Selector (PRI channels)
571 ${CALLINGTON}           * Caller Type of Number (PRI channels)
572 ${CHANNEL}              * Current channel name
573 ${CONTEXT}              * Current context
574 ${DATETIME}             * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%m%Y-%H:%M:%S)})
575 ${DB_RESULT}            Result value of DB_EXISTS() dial plan function
576 ${DNID}                 * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)})
577 ${EPOCH}                * Current unix style epoch
578 ${EXTEN}                * Current extension
579 ${ENV(VAR)}             Environmental variable VAR
580 ${GOTO_ON_BLINDXFR}     Transfer to the specified context/extension/priority
581                         after a blind transfer (use ^ characters in place of
582                         | to separate context/extension/priority when setting
583                         this variable from the dialplan)
584 ${HANGUPCAUSE}          * Asterisk cause of hangup (inbound/outbound)
585 ${HINT}                 * Channel hints for this extension
586 ${HINTNAME}             * Suggested Caller*ID name for this extension
587 ${INVALID_EXTEN}        The invalid called extension (used in the "i" extension)
588 ${LANGUAGE}             * Current language (Deprecated; use ${LANGUAGE()})
589 ${LEN(VAR)}             * String length of VAR (integer)
590 ${PRIORITY}             * Current priority in the dialplan
591 ${PRIREDIRECTREASON}    Reason for redirect on PRI, if a call was directed
592 ${RDNIS}                * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)})
593 ${TIMESTAMP}            * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)})
594 ${TRANSFER_CONTEXT}     Context for transferred calls
595 ${FORWARD_CONTEXT}     Context for forwarded calls
596 ${UNIQUEID}             * Current call unique identifier
597 ${SYSTEMNAME}           * value of the systemname option of asterisk.conf
598 \end{verbatim}
599
600 \subsection{Application return values}
601 -------------------------
602 In Asterisk 1.2, many applications return the result in a variable
603 instead of, as in Asterisk 1.0, changing the dial plan priority (+101).
604 For the various status values, see each application's help text.
605 \begin{verbatim}
606 ${AGISTATUS}                    * agi()
607 ${AQMSTATUS}                    * addqueuemember()
608 ${AVAILSTATUS}                  * chanisavail()
609 ${CHECKGROUPSTATUS}             * checkgroup()
610 ${CHECKMD5STATUS}               * checkmd5()
611 ${CPLAYBACKSTATUS}              * controlplayback()
612 ${DIALSTATUS}                   * dial()
613 ${DBGETSTATUS}                  * dbget()
614 ${ENUMSTATUS}                   * enumlookup()
615 ${HASVMSTATUS}                  * hasnewvoicemail()
616 ${LOOKUPBLSTATUS}               * lookupblacklist()
617 ${OSPAUTHSTATUS}                * ospauth()
618 ${OSPLOOKUPSTATUS}              * osplookup()
619 ${OSPNEXTSTATUS}                * ospnext()
620 ${OSPFINISHSTATUS}              * ospfinish()
621 ${PARKEDAT}                     * parkandannounce()
622 ${PLAYBACKSTATUS}               * playback()
623 ${PQMSTATUS}                    * pausequeuemember()
624 ${PRIVACYMGRSTATUS}             * privacymanager()
625 ${QUEUESTATUS}                  * queue()
626 ${RQMSTATUS}                    * removequeuemember()
627 ${SENDIMAGESTATUS}              * sendimage()
628 ${SENDTEXTSTATUS}               * sendtext()
629 ${SENDURLSTATUS}                * sendurl()
630 ${SYSTEMSTATUS}                 * system()
631 ${TRANSFERSTATUS}               * transfer()
632 ${TXTCIDNAMESTATUS}             * txtcidname()
633 ${UPQMSTATUS}                   * unpausequeuemember()
634 ${VMSTATUS}                     * voicmail()
635 ${VMBOXEXISTSSTATUS}            * vmboxexists()
636 ${WAITSTATUS}                   * waitforsilence()
637 \end{verbatim}
638
639 \subsection{Various application variables}
640 \begin{verbatim}
641 ${CURL}                 * Resulting page content for curl()
642 ${ENUM}                 * Result of application EnumLookup
643 ${EXITCONTEXT}          Context to exit to in IVR menu (app background())
644                         or in the RetryDial() application
645 ${MONITOR}              * Set to "TRUE" if the channel is/has been monitored (app monitor())
646 ${MONITOR_EXEC}         Application to execute after monitoring a call
647 ${MONITOR_EXEC_ARGS}    Arguments to application
648 ${MONITOR_FILENAME}     File for monitoring (recording) calls in queue
649 ${QUEUE_PRIO}           Queue priority
650 ${QUEUE_MAX_PENALTY}    Maximum member penalty allowed to answer caller
651 ${QUEUESTATUS}          Status of the call, one of:
652                         (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
653 ${RECORDED_FILE}        * Recorded file in record()
654 ${TALK_DETECTED}        * Result from talkdetect()
655 ${TOUCH_MONITOR}        The filename base to use with Touch Monitor (auto record)
656 ${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record)
657 ${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record)
658 ${TXTCIDNAME}           * Result of application TXTCIDName
659 ${VPB_GETDTMF}          chan_vpb
660 \end{verbatim}
661
662 \subsection{The MeetMe Conference Bridge}
663 \begin{verbatim}
664 ${MEETME_RECORDINGFILE}         Name of file for recording a conference with 
665                                 the "r" option
666 ${MEETME_RECORDINGFORMAT}       Format of file to be recorded
667 ${MEETME_EXIT_CONTEXT}          Context for exit out of meetme meeting
668 ${MEETME_AGI_BACKGROUND}        AGI script for Meetme (zap only)
669 ${MEETMESECS}                   * Number of seconds a user participated in a MeetMe conference
670 \end{verbatim}
671
672 \subsection{The VoiceMail() application}
673 \begin{verbatim}
674 ${VM_CATEGORY}          Sets voicemail category
675 ${VM_NAME}              * Full name in voicemail
676 ${VM_DUR}               * Voicemail duration
677 ${VM_MSGNUM}            * Number of voicemail message in mailbox
678 ${VM_CALLERID}          * Voicemail Caller ID (Person leaving vm)
679 ${VM_CIDNAME}           * Voicemail Caller ID Name
680 ${VM_CIDNUM}            * Voicemail Caller ID Number
681 ${VM_DATE}              * Voicemail Date
682 ${VM_MESSAGEFILE}       * Path to message left by caller
683 \end{verbatim}
684
685 \subsection{The VMAuthenticate() application}
686 \begin{verbatim}
687 ${AUTH_MAILBOX} * Authenticated mailbox
688 ${AUTH_CONTEXT} * Authenticated mailbox context
689 \end{verbatim}
690
691 \subsection{DUNDiLookup()}
692 \begin{verbatim}
693 ${DUNDTECH}     * The Technology of the result from a call to DUNDiLookup()
694 ${DUNDDEST}     * The Destination of the result from a call to DUNDiLookup()
695 \end{verbatim}
696
697 \subsection{chan\_zap}
698 \begin{verbatim}
699 ${ANI2}                 * The ANI2 Code provided by the network on the incoming call. 
700                         (ie, Code 29 identifies call as a Prison/Inmate Call)
701 ${CALLTYPE}             * Type of call (Speech, Digital, etc)
702 ${CALLEDTON}            * Type of number for incoming PRI extension
703                         i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, 
704                         4=subscriber, 6=abbreviated, 7=reserved 
705 ${CALLINGSUBADDR}       * Called PRI Subaddress
706 ${FAXEXTEN}             * The extension called before being redirected to "fax" 
707 ${PRIREDIRECTREASON}    * Reason for redirect, if a call was directed
708 ${SMDI_VM_TYPE}         * When an call is received with an SMDI message, the 'type'
709                         of message 'b' or 'u'
710 \end{verbatim}
711
712 \subsection{chan\_sip}
713 \begin{verbatim}
714 ${SIPCALLID}            * SIP Call-ID: header verbatim (for logging or CDR matching)
715 ${SIPDOMAIN}            * SIP destination domain of an inbound call (if appropriate)
716 ${SIPUSERAGENT}         * SIP user agent (deprecated)
717 ${SIPURI}               * SIP uri
718 ${SIP_CODEC}            Set the SIP codec for a call    
719 ${SIP_URI_OPTIONS}      * additional options to add to the URI for an outgoing call
720 ${RTPAUDIOQOS}          RTCP QoS report for the audio of this call
721 ${RTPVIDEOQOS}          RTCP QoS report for the video of this call
722 \end{verbatim}
723
724 \subsection{chan\_agent}
725 \begin{verbatim}
726 ${AGENTMAXLOGINTRIES}   Set the maximum number of failed logins
727 ${AGENTUPDATECDR}       Whether to update the CDR record with Agent channel data
728 ${AGENTGOODBYE}         Sound file to use for "Good Bye" when agent logs out
729 ${AGENTACKCALL}         Whether the agent should acknowledge the incoming call
730 ${AGENTAUTOLOGOFF}      Auto logging off for an agent
731 ${AGENTWRAPUPTIME}      Setting the time for wrapup between incoming calls
732 ${AGENTNUMBER}          * Agent number (username) set at login
733 ${AGENTSTATUS}          * Status of login       ( fail | on | off )
734 ${AGENTEXTEN}           * Extension for logged in agent
735 \end{verbatim}
736
737
738 \subsection{The Dial() application}
739 \begin{verbatim}
740 ${DIALEDPEERNAME}               * Dialed peer name
741 ${DIALEDPEERNUMBER}             * Dialed peer number
742 ${DIALEDTIME}                   * Time for the call (seconds)
743 ${ANSWEREDTIME}                 * Time from dial to answer (seconds)
744 ${DIALSTATUS}                   * Status of the call, one of:
745                                 (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER 
746                                         | ANSWER | CANCEL | DONTCALL | TORTURE)
747 ${DYNAMIC_FEATURES}             * The list of features (from the [applicationmap] section of
748                                   features.conf) to activate during the call, with feature
749                                   names separated by '#' characters
750 ${LIMIT_PLAYAUDIO_CALLER}       Soundfile for call limits
751 ${LIMIT_PLAYAUDIO_CALLEE}       Soundfile for call limits
752 ${LIMIT_WARNING_FILE}           Soundfile for call limits
753 ${LIMIT_TIMEOUT_FILE}           Soundfile for call limits
754 ${LIMIT_CONNECT_FILE}           Soundfile for call limits
755 ${OUTBOUND_GROUP}               Default groups for peer channels (as in SetGroup)
756 * See "show application dial" for more information
757 \end{verbatim}
758
759 \subsection{The chanisavail() application}
760 \begin{verbatim}
761 ${AVAILCHAN}            * the name of the available channel if one was found    
762 ${AVAILORIGCHAN}        * the canonical channel name that was used to create the channel
763 ${AVAILSTATUS}          * Status of requested channel
764 \end{verbatim}
765
766 \subsection{Dialplan Macros}
767 \begin{verbatim}
768 ${MACRO_EXTEN}          * The calling extensions
769 ${MACRO_CONTEXT}        * The calling context
770 ${MACRO_PRIORITY}       * The calling priority
771 ${MACRO_OFFSET}         Offset to add to priority at return from macro
772 \end{verbatim}
773
774 \subsection{The ChanSpy() application}
775 \begin{verbatim}
776 ${SPYGROUP}             * A ':' (colon) separated list of group names.
777                           (To be set on spied on channel and matched against the g(grp) option)
778 \end{verbatim}
779
780 \subsection{OSP}
781 \begin{verbatim}
782 ${OSPINHANDLE}          OSP handle of in_bound call
783 ${OSPINTIMELIMIT}       Duration limit for in_bound call
784 ${OSPOUTHANDLE}         OSP handle of out_bound call
785 ${OSPTECH}              OSP technology 
786 ${OSPDEST}              OSP destination
787 ${OSPCALLING}           OSP calling number
788 ${OSPOUTTOKEN}          OSP token to use for out_bound call
789 ${OSPOUTTIMELIMIT}      Duration limit for out_bound call
790 ${OSPRESULTS}           Number of remained destinations
791 \end{verbatim}