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