doc/README.variables

   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, it is ignored and Asterisk will match
 143 to the end of the string.
 144 ___________________________
 145 EXPRESSIONS:
 146 ---------------------------
 147
 148 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is
 149 considered as an expression and it is evaluated. Evaluation works similar to
 150 (but is done on a later stage than) variable substitution: the expression
 151 (including the square brackets) is replaced by the result of the expression
 152 evaluation.
 153
 154 For example, after the sequence:
 155
 156 exten => 1,1,Set(lala=$[1 + 2])
 157 exten => 1,2,Set(koko=$[2 * ${lala}])
 158
 159 the value of variable koko is "6".
 160
 161 and, further:
 162
 163 exten => 1,1,Set,(lala=$[  1 +    2   ]);
 164
 165 will parse as intended. Extra spaces are ignored.
 166
 167
 168 ______________________________
 169 SPACES INSIDE VARIABLE VALUES
 170 ------------------------------
 171 If the variable being evaluated contains spaces, there can be problems.
 172
 173 For these cases, double quotes around text that may contain spaces
 174 will force the surrounded text to be evaluated as a single token.
 175 The double quotes will be counted as part of that lexical token.
 176
 177 As an example:
 178
 179 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
 180
 181 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
 182 but the above will evaluate to:
 183
 184 "DELOREAN MOTORS" : "Privacy Manager"
 185
 186 and will evaluate to 0.
 187
 188 The above without double quotes would have evaluated to:
 189
 190 DELOREAN MOTORS : Privacy Manager
 191
 192 and will result in syntax errors, because token DELOREAN is immediately
 193 followed by token MOTORS and the expression parser will not know how to
 194 evaluate this expression, because it does not match its grammar.
 195
 196 _____________________
 197 OPERATORS
 198 ---------------------
 199 Operators are listed below in order of increasing precedence.  Operators
 200 with equal precedence are grouped within { } symbols.
 201
 202      expr1 | expr2
 203              Return the evaluation of expr1 if it is neither an empty string
 204              nor zero; otherwise, returns the evaluation of expr2.
 205
 206      expr1 & expr2
 207              Return the evaluation of expr1 if neither expression evaluates to
 208              an empty string or zero; otherwise, returns zero.
 209
 210      expr1 {=, >, >=, <, <=, !=} expr2
 211              Return the results of integer comparison if both arguments are
 212              integers; otherwise, returns the results of string comparison
 213              using the locale-specific collation sequence.  The result of each
 214              comparison is 1 if the specified relation is true, or 0 if the
 215              relation is false.
 216
 217      expr1 {+, -} expr2
 218              Return the results of addition or subtraction of integer-valued
 219              arguments.
 220
 221      expr1 {*, /, %} expr2
 222              Return the results of multiplication, integer division, or
 223              remainder of integer-valued arguments.
 224
 225      - expr1
 226             Return the result of subtracting expr1 from 0.
 227             This, the unary minus operator, is right associative, and
 228             has the same precedence as the ! operator.
 229
 230      ! expr1
 231             Return the result of a logical complement of expr1.
 232             In other words, if expr1 is null, 0, an empty string,
 233             or the string "0", return a 1. Otherwise, return a 0.
 234             It has the same precedence as the unary minus operator, and
 235             is also right associative.
 236
 237      expr1 : expr2
 238              The `:' operator matches expr1 against expr2, which must be a
 239              regular expression.  The regular expression is anchored to the
 240              beginning of  the string with an implicit `^'.
 241
 242              If the match succeeds and the pattern contains at least one regu-
 243              lar expression subexpression `\(...\)', the string correspond-
 244              ing to `\1' is returned; otherwise the matching operator
 245              returns the number of characters matched.  If the match fails and
 246              the pattern contains a regular expression subexpression the null
 247              string is returned; otherwise 0.
 248
 249              Normally, the double quotes wrapping a string are left as part
 250              of the string. This is disastrous to the : operator. Therefore,
 251              before the regex match is made, beginning and ending double quote
 252              characters are stripped from both the pattern and the string.
 253
 254       expr1 =~ expr2
 255              Exactly the same as the ':' operator, except that the match is
 256              not anchored to the beginning of the string. Pardon any similarity
 257              to seemingly similar operators in other programming languages!
 258              The ":" and "=~" operators share the same precedence.
 259
 260       expr1 ? expr2 :: expr3
 261              Traditional Conditional operator. If expr1 is a number
 262              that evaluates to 0 (false), expr3 is result of the this
 263              expression evaluation.  Otherwise, expr2 is the result.
 264              If expr1 is a string, and evaluates to an empty string,
 265              or the two characters (""), then expr3 is the
 266              result. Otherwise, expr2 is the result.  In Asterisk, all
 267              3 exprs will be "evaluated"; if expr1 is "true", expr2
 268              will be the result of the "evaluation" of this
 269              expression.  expr3 will be the result otherwise. This
 270              operator has the lowest precedence.
 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 Examples
 278
 279  "One Thousand Five Hundred" =~ "(T[^ ]+)"
 280         returns: Thousand
 281
 282  "One Thousand Five Hundred" =~ "T[^ ]+"
 283         returns: 8
 284
 285  "One Thousand Five Hundred" : "T[^ ]+"
 286         returns: 0
 287
 288  "8015551212" : "(...)"
 289         returns: 801
 290
 291  "3075551212":"...(...)"
 292         returns: 555
 293
 294  ! "One Thousand Five Hundred" =~ "T[^ ]+"
 295         returns: 0 (because it applies to the string, which is non-null,
 296                     which it turns to "0", and then looks for the pattern
 297                     in the "0", and doesn't find it)
 298
 299  !( "One Thousand Five Hundred" : "T[^ ]+" )
 300         returns: 1  (because the string doesn't start with a word starting
 301                      with T, so the match evals to 0, and the ! operator
 302                      inverts it to 1 ).
 303
 304  2 + 8 / 2
 305         returns 6. (because of operator precedence; the division is done first, then the addition).
 306
 307  2+8/2
 308         returns 6. Spaces aren't necessary.
 309
 310 (2+8)/2
 311         returns 5, of course.
 312
 313 Of course, all of the above examples use constants, but would work the
 314 same if any of the numeric or string constants were replaced with a
 315 variable reference ${CALLERIDNUM}, for instance.
 316
 317 __________________________
 318 NUMBERS VS STRINGS
 319 --------------------------
 320
 321 Tokens consisting only of numbers are converted to 64-bit numbers for
 322 most of the operators. This means that overflows can occur when the
 323 numbers get above 18 digits.  Warnings will appear in the logs in this
 324 case.
 325 ___________________________
 326 CONDITIONALS
 327 ---------------------------
 328
 329 There is one conditional application - the conditional goto :
 330
 331         exten => 1,2,gotoif(condition?label1:label2)
 332
 333 If condition is true go to label1, else go to label2. Labels are interpreted
 334 exactly as in the normal goto command.
 335
 336 "condition" is just a string. If the string is empty or "0", the condition
 337 is considered to be false, if it's anything else, the condition is true.
 338 This is designed to be used together with the expression syntax described
 339 above, eg :
 340
 341         exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
 342
 343 Example of use :
 344
 345 exten => s,2,Set(vara=1)
 346 exten => s,3,Set(varb=$[${vara} + 2])
 347 exten => s,4,Set(varc=$[${varb} * 2])
 348 exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
 349
 350 ___________________________
 351 PARSE ERRORS
 352 ---------------------------
 353
 354 Syntax errors are now output with 3 lines.
 355
 356 If the extensions.conf file contains a line like:
 357
 358 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & &  "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
 359
 360 You may see an error in /var/log/asterisk/messages like this:
 361
 362 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:
 363 "3072312154"  = "3071234567" & & "Steves Extension" : "Privacy Manager"
 364                                ^
 365
 366 The log line tells you that a syntax error was encountered. It now
 367 also tells you (in grand standard bison format) that it hit an "AND"
 368 (&) token unexpectedly, and that was hoping for for a MINUS (-), LP
 369 (left parenthesis), or a plain token (a string or number).
 370
 371 The next line shows the evaluated expression, and the line after
 372 that, the position of the parser in the expression when it became confused,
 373 marked with the "^" character.
 374
 375 ___________________________
 376 NULL STRINGS
 377 ---------------------------
 378
 379 Testing to see if a string is null can be done in one of two different ways:
 380
 381         exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)
 382
 383         exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
 384
 385
 386 The second example above is the way suggested by the WIKI. It will
 387 work as long as there are no spaces in the evaluated value.
 388
 389 The first way should work in all cases, and indeed, might now
 390 be the safest way to handle this situation.
 391
 392 ___________________________
 393 WARNING
 394 ---------------------------
 395
 396 If you need to do complicated things with strings, asterisk expressions
 397 is most likely NOT the best way to go about it. AGI scripts are an
 398 excellent option to this need, and make available the full power of
 399 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
 400 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
 401 Pascal, APL, assembler, etc.
 402
 403 ----------------------------
 404 INCOMPATIBILITIES
 405 ----------------------------
 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 1. Tokens separated by space(s).
 432    Previously, tokens were separated by spaces. Thus, ' 1 + 1 ' would evaluate
 433    to the value '2', but '1+1' would evaluate to the string '1+1'. If this
 434    behavior was depended on, then the expression evaluation will break. '1+1'
 435    will now evaluate to '2', and something is not going to work right.
 436    To keep such strings from being evaluated, simply wrap them in double
 437    quotes: '  "1+1" '
 438
 439 2. The colon operator. In versions previous to double quoting, the
 440    colon operator takes the right hand string, and using it as a
 441    regex pattern, looks for it in the left hand string. It is given
 442    an implicit ^ operator at the beginning, meaning the pattern
 443    will match only at the beginning of the left hand string.
 444    If the pattern or the matching string had double quotes around
 445    them, these could get in the way of the pattern match. Now,
 446    the wrapping double quotes are stripped from both the pattern
 447    and the left hand string before applying the pattern. This
 448    was done because it recognized that the new way of
 449    scanning the expression doesn't use spaces to separate tokens,
 450    and the average regex expression is full of operators that
 451    the scanner will recognize as expression operators. Thus, unless
 452    the pattern is wrapped in double quotes, there will be trouble.
 453    For instance,      ${VAR1} : (Who|What*)+
 454    may have have worked before, but unless you wrap the pattern
 455    in double quotes now, look out for trouble! This is better:
 456          "${VAR1}" : "(Who|What*)+"
 457    and should work as previous.
 458
 459 3. Variables and Double Quotes
 460    Before these changes, if a variable's value contained one or more double
 461    quotes, it was no reason for concern. It is now!
 462
 463 4. LE, GE, NE operators removed. The code supported these operators,
 464    but they were not documented. The symbolic operators, <=, >=, and !=
 465    should be used instead.
 466
 467 5.  Added the unary '-' operator. So you can 3+ -4 and get -1.
 468
 469 6.  Added the unary '!' operator, which is a logical complement.
 470     Basically, if the string or number is null, empty, or '0',
 471     a '1' is returned. Otherwise a '0' is returned.
 472
 473 7.  Added the '=~' operator, just in case someone is just looking for
 474     match anywhere in the string. The only diff with the ':' is that
 475     match doesn't have to be anchored to the beginning of the string.
 476
 477 8.  Added the conditional operator  'expr1 ? true_expr :: false_expr'
 478     First, all 3 exprs are evaluated, and if expr1 is false, the 'false_expr'
 479     is returned as the result. See above for details.
 480
 481 9.  Unary operators '-' and '!' were made right associative.
 482
 483 --------------------------------------------------------
 484 DEBUGGING HINTS FOR $[  ]  EXPRESSIONS
 485 --------------------------------------------------------
 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 ---------------------------------------------------------
 550 Asterisk standard channel variables
 551 ---------------------------------------------------------
 552 There are a number of variables that are defined or read
 553 by Asterisk. Here is a list of them. More information is
 554 available in each application's help text. All these variables
 555 are in UPPER CASE only.
 556
 557 Variables marked with a * are builtin functions and can't be set,
 558 only read in the dialplan.  Writes to such variables are silently
 559 ignored.
 560
 561 ${ACCOUNTCODE}          * Account code (if specified)
 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)
 565 ${CALLERID}             * Caller ID
 566 ${CALLERIDNAME}         * Caller ID Name only
 567 ${CALLERIDNUM}          * Caller ID Number only
 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
 575 ${DB_RESULT}            Result value of DB_EXISTS() dial plan function
 576 ${DNID}                 * Dialed Number Identifier
 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
 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
 593 ${TIMESTAMP}            * Current date time in the format: YYYYMMDD-HHMMSS
 594 ${TRANSFER_CONTEXT}     Context for transferred calls
 595 ${UNIQUEID}             * Current call unique identifier
 596
 597 Application return values
 598 -------------------------
 599 In Asterisk 1.2, many applications return the result in a variable
 600 instead of, as in Asterisk 1.0, changing the dial plan priority (+101).
 601 For the various status values, see each application's help text.
 602
 603 ${AQMSTATUS}                    * addqueuemember()
 604 ${AVAILSTATUS}                  * chanisavail()
 605 ${CHECKGROUPSTATUS}             * checkgroup()
 606 ${CHECKMD5STATUS}               * checkmd5()
 607 ${CPLAYBACKSTATUS}              * controlplayback()
 608 ${DIALSTATUS}                   * dial()
 609 ${DBGETSTATUS}                  * dbget()
 610 ${ENUMSTATUS}                   * enumlookup()
 611 ${HASVMSTATUS}                  * hasnewvoicemail()
 612 ${LOOKUPBLSTATUS}               * lookupblacklist()
 613 ${OSPLOOKUPSTATUS}              * osplookup()
 614 ${OSPNEXTSTATUS}                * ospnext()
 615 ${OSPFINISHSTATUS}              * ospfinish()
 616 ${PLAYBACKSTATUS}               * playback()
 617 ${PQMSTATUS}                    * pausequeuemember()
 618 ${PRIVACYMGRSTATUS}             * privacymanager()
 619 ${QUEUESTATUS}                  * queue()
 620 ${RQMSTATUS}                    * removequeuemember()
 621 ${SENDIMAGESTATUS}              * sendimage()
 622 ${SENDTEXTSTATUS}               * sendtext()
 623 ${SENDURLSTATUS}                * sendurl()
 624 ${SYSTEMSTATUS}                 * system()
 625 ${TRANSFERSTATUS}               * transfer()
 626 ${TXTCIDNAMESTATUS}             * txtcidname()
 627 ${UPQMSTATUS}                   * unpausequeuemember()
 628 ${VMSTATUS}                     * voicmail()
 629 ${VMBOXEXISTSSTATUS}            * vmboxexists()
 630 ${WAITSTATUS}                   * waitforsilence()
 631
 632
 633 Various application variables
 634 -----------------------------
 635 ${CURL}                 * Resulting page content for curl()
 636 ${ENUM}                 * Result of application EnumLookup
 637 ${EXITCONTEXT}          Context to exit to in IVR menu (app background())
 638                         or in the RetryDial() application
 639 ${MONITOR}              * Set to "TRUE" if the channel is/has been monitored (app monitor())
 640 ${MONITOR_EXEC}         Application to execute after monitoring a call
 641 ${MONITOR_EXEC_ARGS}    Arguments to application
 642 ${MONITOR_FILENAME}     File for monitoring (recording) calls in queue
 643 ${QUEUE_PRIO}           Queue priority
 644 ${QUEUE_MAX_PENALTY}    Maximum member penalty allowed to answer caller
 645 ${QUEUESTATUS}          Status of the call, one of:
 646                         (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
 647 ${RECORDED_FILE}        * Recorded file in record()
 648 ${TALK_DETECTED}        * Result from talkdetect()
 649 ${TOUCH_MONITOR}        The filename base to use with Touch Monitor (auto record)
 650 ${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record)
 651 ${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record)
 652 ${TXTCIDNAME}           * Result of application TXTCIDName
 653 ${VPB_GETDTMF}          chan_vpb
 654
 655 The MeetMe Conference Bridge uses the following variables:
 656 ----------------------------------------------------------
 657 ${MEETME_RECORDINGFILE}         Name of file for recording a conference with
 658                                 the "r" option
 659 ${MEETME_RECORDINGFORMAT}       Format of file to be recorded
 660 ${MEETME_EXIT_CONTEXT}          Context for exit out of meetme meeting
 661 ${MEETME_AGI_BACKGROUND}        AGI script for Meetme (zap only)
 662 ${MEETMESECS}                   * Number of seconds a user participated in a MeetMe conference
 663
 664 The VoiceMail() application uses the following variables:
 665 ---------------------------------------------------------
 666 ${VM_CATEGORY}          Sets voicemail category
 667 ${VM_NAME}              * Full name in voicemail
 668 ${VM_DUR}               * Voicemail duration
 669 ${VM_MSGNUM}            * Number of voicemail message in mailbox
 670 ${VM_CALLERID}          * Voicemail Caller ID (Person leaving vm)
 671 ${VM_CIDNAME}           * Voicemail Caller ID Name
 672 ${VM_CIDNUM}            * Voicemail Caller ID Number
 673 ${VM_DATE}              * Voicemail Date
 674 ${VM_MESSAGEFILE}       * Path to message left by caller
 675
 676 The VMAuthenticate() application uses the following variables:
 677 ---------------------------------------------------------
 678 ${AUTH_MAILBOX} * Authenticated mailbox
 679 ${AUTH_CONTEXT} * Authenticated mailbox context
 680
 681 DUNDiLookup() uses the following variables
 682 ---------------------------------------------------------
 683 ${DUNDTECH}     * The Technology of the result from a call to DUNDiLookup()
 684 ${DUNDDEST}     * The Destination of the result from a call to DUNDiLookup()
 685
 686 The Zaptel channel sets the following variables:
 687 ---------------------------------------------------------
 688 ${ANI2}                 * The ANI2 Code provided by the network on the incoming call.
 689                         (ie, Code 29 identifies call as a Prison/Inmate Call)
 690 ${CALLTYPE}             * Type of call (Speech, Digital, etc)
 691 ${CALLEDTON}            * Type of number for incoming PRI extension
 692                         i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific,
 693                         4=subscriber, 6=abbreviated, 7=reserved
 694 ${CALLINGSUBADDR}       * Called PRI Subaddress
 695 ${FAXEXTEN}             * The extension called before being redirected to "fax"
 696 ${PRIREDIRECTREASON}    * Reason for redirect, if a call was directed
 697
 698 The SIP channel uses the following variables:
 699 ---------------------------------------------------------
 700 ${SIPCALLID}            * SIP Call-ID: header verbatim (for logging or CDR matching)
 701 ${SIPDOMAIN}            * SIP destination domain of an inbound call (if appropriate)
 702 ${SIPUSERAGENT}         * SIP user agent
 703 ${SIPURI}               * SIP uri
 704 ${SIP_CODEC}            Set the SIP codec for a call
 705 ${SIP_URI_OPTIONS}      * additional options to add to the URI for an outgoing call
 706
 707 The Agent channel uses the following variables:
 708 ---------------------------------------------------------
 709 ${AGENTMAXLOGINTRIES}   Set the maximum number of failed logins
 710 ${AGENTUPDATECDR}       Whether to update the CDR record with Agent channel data
 711 ${AGENTGOODBYE}         Sound file to use for "Good Bye" when agent logs out
 712 ${AGENTACKCALL}         Whether the agent should acknowledge the incoming call
 713 ${AGENTAUTOLOGOFF}      Auto logging off for an agent
 714 ${AGENTWRAPUPTIME}      Setting the time for wrapup between incoming calls
 715 ${AGENTNUMBER}          * Agent number (username) set at login
 716 ${AGENTSTATUS}          * Status of login       ( fail | on | off )
 717 ${AGENTEXTEN}           * Extension for logged in agent
 718
 719 The Dial() application uses the following variables:
 720 ---------------------------------------------------------
 721 ${DIALEDPEERNAME}               * Dialed peer name
 722 ${DIALEDPEERNUMBER}             * Dialed peer number
 723 ${DIALEDTIME}                   * Time for the call (seconds)
 724 ${ANSWEREDTIME}                 * Time from dial to answer (seconds)
 725 ${DIALSTATUS}                   * Status of the call, one of:
 726                                 (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER
 727                                         | ANSWER | CANCEL | DONTCALL | TORTURE)
 728 ${DYNAMIC_FEATURES}             * The list of features (from the [applicationmap] section of
 729                                   features.conf) to activate during the call, with feature
 730                                   names separated by '#' characters
 731 ${LIMIT_PLAYAUDIO_CALLER}       Soundfile for call limits
 732 ${LIMIT_PLAYAUDIO_CALLEE}       Soundfile for call limits
 733 ${LIMIT_WARNING_FILE}           Soundfile for call limits
 734 ${LIMIT_TIMEOUT_FILE}           Soundfile for call limits
 735 ${LIMIT_CONNECT_FILE}           Soundfile for call limits
 736 ${OUTBOUND_GROUP}               Default groups for peer channels (as in SetGroup)
 737 * See "show application dial" for more information
 738
 739 The chanisavail() application sets the following variables:
 740 -----------------------------------------------------------
 741 ${AVAILCHAN}            * the name of the available channel if one was found
 742 ${AVAILORIGCHAN}        * the canonical channel name that was used to create the channel
 743 ${AVAILSTATUS}          * Status of requested channel
 744
 745 When using macros in the dialplan, these variables are available
 746 ---------------------------------------------------------
 747 ${MACRO_EXTEN}          * The calling extensions
 748 ${MACRO_CONTEXT}        * The calling context
 749 ${MACRO_PRIORITY}       * The calling priority
 750 ${MACRO_OFFSET}         Offset to add to priority at return from macro
 751
 752 If you compile with OSP support in the SIP channel, these
 753 variables are used:
 754 ---------------------------------------------------------
 755 ${OSPHANDLE}            Handle from the OSP Library
 756 ${OSPTECH}              OSP Technology from Library
 757 ${OSPDEST}              OSP Destination from Library
 758 ${OSPTOKEN}             OSP Token to use for call from Library
 759 ${OSPRESULTS}           Number of OSP results
 760
 761 ____________________________________
 762 CDR Variables
 763 ------------------------------------
 764
 765 If the channel has a cdr, that cdr record has it's own set of variables which
 766 can be accessed just like channel variables. The following builtin variables
 767 are available.
 768
 769 ${CDR(clid)}                    Caller ID
 770 ${CDR(src)}                     Source
 771 ${CDR(dst)}                     Destination
 772 ${CDR(dcontext)}                Destination context
 773 ${CDR(channel)}                 Channel name
 774 ${CDR(dstchannel)}              Destination channel
 775 ${CDR(lastapp)}                 Last app executed
 776 ${CDR(lastdata)}                Last app's arguments
 777 ${CDR(start)}                   Time the call started.
 778 ${CDR(answer)}                  Time the call was answered.
 779 ${CDR(end)}                     Time the call ended.
 780 ${CDR(duration)}                Duration of the call.
 781 ${CDR(billsec)}                 Duration of the call once it was answered.
 782 ${CDR(disposition)}             ANSWERED, NO ANSWER, BUSY
 783 ${CDR(amaflags)}                DOCUMENTATION, BILL, IGNORE etc
 784 ${CDR(accountcode)}             The channel's account code.
 785 ${CDR(uniqueid)}                The channel's unique id.
 786 ${CDR(userfield)}               The channels uses specified field.
 787
 788
 789 In addition, you can set your own extra variables with a traditional
 790 SetVAR(CDR(var)=val) to anything you want.
 791
 792 Certain functional variables may be accessed with $(foo <args>).  A list
 793 of these functional variables may be found by typing "show functions"
 794 at the Asterisk CLI.