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