Add new variable for PRIREDIRECTREASON in dial plan if you a call is redirected
[asterisk/asterisk.git] / doc / README.variables
1 EXTENSION LOGIC : 
2
3 There are two levels of parameter evaluation done in asterisk in 
4 extensions.conf.
5 The first, and most frequently used, is the substitution of variable
6 references with their values. 
7
8 Then there are the evaluations done in $[ .. ]. This will be
9 discussed below.
10
11 ___________________________
12 PARAMETER QUOTING: 
13 ---------------------------
14
15 exten => s,5,BackGround,blabla
16
17 The parameter (blabla) can be quoted ("blabla"). In this case, a 
18 comma does not terminate the field. However, the double quotes
19 will be passed down to the Background command, in this example.
20
21 Also, characters special to variable substitution, expression evaluation, etc
22 (see below), can be quoted. For example, to literally use a $ on the 
23 string "$1231", quote it with a preceding \. Special characters that must
24 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). 
25
26 These Double quotes and escapes are evaluated at the level of the
27 asterisk config file parser. 
28
29 Double quotes can also be used inside expressions, as discussed below.
30
31
32 ___________________________
33 VARIABLES: 
34 ---------------------------
35
36 Parameter strings can include variables. Variable names are arbitrary strings. 
37 They are stored in the respective channel structure. 
38
39 To set a variable to a particular value, do : 
40
41 ;exten => 1,2,SetVar,varname=value
42
43 You can substitute the value of a variable everywhere using ${variablename}.
44 For example, to stringwise append $lala to $blabla and store result in $koko, 
45 do: 
46
47 ;exten => 1,2,SetVar,koko=${blabla}${lala}
48
49 There are also the following special variables: 
50
51 ${ACCOUNTCODE}  Account code (if specified)
52 ${CALLERID}     Caller ID
53 ${CALLERIDNAME} Caller ID Name only
54 ${CALLERIDNUM}  Caller ID Number only
55 ${CALLINGPRES}  PRI Caller ID presentation for incoming calls
56 ${CHANNEL}      Current channel name
57 ${CONTEXT}      Current context
58 ${DATETIME}     Current date time in the format: YYYY-MM-DD_HH:MM:SS
59 ${DNID}         Dialed Number Identifier
60 ${ENUM}         Result of application EnumLookup
61 ${EPOCH}        Current unix style epoch
62 ${EXTEN}        Current extension
63 ${ENV(VAR)}     Environmental variable VAR
64 ${HANGUPCAUSE}  Asterisk hangup cause
65 ${INVALID_EXTEN}The invalid called extension (used in the "i" extension)
66 ${LANGUAGE}     Current language
67 ${LEN(VAR)}     String length of VAR (integer)
68 ${MEETMESECS}   Number of seconds a user participated in a MeetMe conference
69 ${PRIORITY}     Current priority
70 ${RDNIS}        Redirected Dial Number ID Service
71 ${SIPCALLID}    SIP Call-ID: header verbatim (for logging or CDR matching)
72 ${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
73 ${SIPUSERAGENT} SIP user agent 
74 ${TIMESTAMP}    Current date time in the format: YYYYMMDD-HHMMSS
75 ${TXTCIDNAME}   Result of application TXTCIDName
76 ${UNIQUEID}     Current call unique identifier
77 ${PRIREDIRECTREASON} Reason for redirect, if a call was directed
78
79 The dial() application sets the following variables:
80
81 ${DIALEDPEERNAME} Dialed peer name
82 ${DIALEDPEERNUMBER} Dialed peer number
83 ${DIALEDTIME}   Time for the call (seconds)
84 ${ANSWEREDTIME} Time from dial to answer (seconds)
85 ${DIALSTATUS}   Status of the call, one of:
86                 CHANUNAVAIL | CONGESTION | BUSY | NOANSWER | ANSWER | CANCEL
87
88 There are two reference modes - reference by value and reference by name. 
89 To refer to a variable with its name (as an argument to a function that 
90 requires a variable), just write the name. To refer to the variable's value, 
91 enclose it inside ${}. For example, SetVar takes as the first argument 
92 (before the =) a variable name, so: 
93
94 ;exten => 1,2,SetVar,koko=lala
95 ;exten => 1,3,SetVar,${koko}=blabla
96
97 stores to the variable "koko" the value "lala" and to variable "lala" the 
98 value "blabla". 
99
100 In fact, everything contained ${here} is just replaced with the value of 
101 the variable "here". 
102
103 ___________________________
104 EXPRESSIONS: 
105 ---------------------------
106
107 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is 
108 considered as an expression and it is evaluated. Evaluation works similar to 
109 (but is done on a later stage than) variable substitution: the expression 
110 (including the square brackets) is replaced by the result of the expression 
111 evaluation. The arguments and operands of the expression MUST BE separated 
112 by at least one space. 
113
114
115 For example, after the sequence: 
116
117 exten => 1,1,SetVar,"lala=$[1 + 2]";
118 exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
119
120 the value of variable koko is "6".
121
122 And, further:
123
124 exten => 1,1,SetVar,"lala=$[1+2]";
125
126 will not work as you might have expected. Since all the chars in the single 
127 token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
128 please do not forget, that this is a very simple parsing engine, and it
129 uses a space (at least one), to separate "tokens".
130
131 and, further:
132
133 exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
134
135 will parse as intended. Extra spaces are ignored.
136
137 ___________________________
138 SPACES INSIDE VARIABLE
139 ---------------------------
140 If the variable being evaluated contains spaces, there can be problems.
141
142 For these cases, double quotes around text that may contain spaces
143 will force the surrounded text to be evaluated as a single token.
144 The double quotes will be counted as part of that lexical token.
145
146 As an example:
147
148 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
149
150 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
151 but the above will evaluate to:
152
153 "DELOREAN MOTORS" : "Privacy Manager"
154
155 and will evaluate to 0.
156
157 The above without double quotes would have evaluated to:
158
159 DELOREAN MOTORS : Privacy Manager
160
161 and will result in syntax errors, because token DELOREAN is immediately
162 followed by token MOTORS and the expression parser will not know how to 
163 evaluate this expression.
164
165 _____________________
166 OPERATORS
167 ---------------------
168 Operators are listed below in order of increasing precedence.  Operators
169 with equal precedence are grouped within { } symbols.
170
171      expr1 | expr2
172              Return the evaluation of expr1 if it is neither an empty string
173              nor zero; otherwise, returns the evaluation of expr2.
174
175      expr1 & expr2
176              Return the evaluation of expr1 if neither expression evaluates to
177              an empty string or zero; otherwise, returns zero.
178
179      expr1 {=, >, >=, <, <=, !=} expr2
180              Return the results of integer comparison if both arguments are
181              integers; otherwise, returns the results of string comparison
182              using the locale-specific collation sequence.  The result of each
183              comparison is 1 if the specified relation is true, or 0 if the
184              relation is false.
185
186      expr1 {+, -} expr2
187              Return the results of addition or subtraction of integer-valued
188              arguments.
189
190      expr1 {*, /, %} expr2
191              Return the results of multiplication, integer division, or
192              remainder of integer-valued arguments.
193
194      expr1 : expr2
195              The `:' operator matches expr1 against expr2, which must be a
196              regular expression.  The regular expression is anchored to the
197              beginning of  the string with an implicit `^'.
198
199              If the match succeeds and the pattern contains at least one regu-
200              lar expression subexpression `\(...\)', the string correspond-
201              ing to `\1' is returned; otherwise the matching operator
202              returns the number of characters matched.  If the match fails and
203              the pattern contains a regular expression subexpression the null
204              string is returned; otherwise 0.
205
206 Parentheses are used for grouping in the usual manner.
207
208 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
209 produce pure parsers, which are reentrant) 
210
211 ___________________________
212 CONDITIONALS
213 ---------------------------
214
215 There is one conditional operator - the conditional goto : 
216
217 ;exten => 1,2,gotoif,condition?label1:label2
218
219 If condition is true go to label1, else go to label2. Labels are interpreted
220 exactly as in the normal goto command.
221
222 "condition" is just a string. If the string is empty or "0", the condition
223 is considered to be false, if it's anything else, the condition is true. 
224 This is designed to be used together with the expression syntax described 
225 above, eg : 
226
227 exten => 1,2,gotoif,$[${CALLERID} = 123456]?2|1:3|1
228
229
230 Example of use : 
231
232 exten => s,2,SetVar,"vara=1"
233 exten => s,3,SetVar,"varb=$[${vara} + 2]"
234 exten => s,4,SetVar,"varc=$[${varb} * 2]"
235 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
236
237 ___________________________
238 PARSE ERRORS
239 ---------------------------
240
241 Syntax errors are now output with 3 lines.
242
243 If the extensions.conf file contains a line like:
244
245 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
246
247 You may see an error in /var/log/asterisk/messages like this:
248
249 May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
250  "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
251  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
252                                   ^
253
254 The first line shows the string passed to the expression parser. This
255 string is the result of the variable replacements, etc. This way, you
256 can see the actual string that went into the parser.
257
258 The second line usually shows a string of '^' chars, that show what's
259 been legally parsed so far.
260
261 And the third line shows where the parser was (lookahead token lexing,
262 etc), when the parse hit the rocks. A single '^' here. The error is
263 going to be somewhere between the last '^' on the second line, and the
264 '^' on the third line. That's right, in the example above, there are two
265 '&' chars, separated by a space, and this is a definite no-no!
266
267
268 ___________________________
269 NULL STRINGS
270 ---------------------------
271
272 Testing to see if a string is null can be done in one of two different ways:
273
274 exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
275
276 exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
277
278
279 The second example above is the way suggested by the WIKI. It will 
280 work as long as there are no spaces in the evaluated value.
281
282 The first way should work in all cases, and indeed, might now
283 be the safest way to handle this situation.
284
285 ___________________________
286 WARNING
287 ---------------------------
288
289 If you need to do complicated things with strings, asterisk expressions
290 is most likely NOT the best way to go about it. AGI scripts are an
291 excellent option to this need, and make available the full power of
292 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
293 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
294 Pascal, APL, assembler, etc.
295