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