README.variables

   1 GENERAL ENCHANCEMENTS TO EXTENSION LOGIC :
   2
   3 QUOTING:
   4
   5 exten => s,5,BackGround,blabla
   6
   7 The parameter (blabla) can be quoted ("blabla"). In this case, a
   8 comma does not terminate the field.
   9
  10 Also, characters special to variable substitution, expression evaluation, etc
  11 (see below), can be quoted. For example, to literally use a $ on the
  12 string "$1231", quote it with a preceeding \. Special characters that must
  13 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\).
  14
  15 VARIABLES:
  16
  17 Parameter strings can include variables. Variable names are arbitrary strings.
  18 They are stored in the respective channel structure.
  19
  20 To set a variable to a particular value, do :
  21
  22 ;exten => 1,2,SetVar,varname=value
  23
  24 You can substitute the value of a variable everywhere using ${variablename}.
  25 For example, to stringwise append $lala to $blabla and store result in $koko,
  26 do:
  27
  28 ;exten => 1,2,SetVar,koko=${blabla}${lala}
  29
  30 There are also the following special variables:
  31
  32 ${CALLERID}     Caller ID
  33 ${CALLERIDNAME} Caller ID Name only
  34 ${CALLERIDNUM}  Caller ID Number only
  35 ${EXTEN}        Current extension
  36 ${CONTEXT}      Current context
  37 ${PRIORITY}     Current priority
  38 ${CHANNEL}      Current channel name
  39 ${ENV(VAR)}     Environmental variable VAR
  40 ${LEN(VAR)}     String length of VAR (integer)
  41 ${EPOCH}        Current unix style epoch
  42 ${DATETIME}     Current date time in the format: YYYY-MM-DD_HH:MM:SS
  43 ${UNIQUEID}     Current call unique identifier
  44 ${DNID}         Dialed Number Identifier
  45 ${RDNIS}        Redirected Dial Number ID Service
  46 ${HANGUPCAUSE}  Hangup cause on last PRI hangup
  47 ${ACCOUNTCODE}  Account code (if specified)
  48
  49 ${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
  50
  51 There are two reference modes - reference by value and reference by name.
  52 To refer to a variable with its name (as an argument to a function that
  53 requires a variable), just write the name. To refer to the variable's value,
  54 enclose it inside ${}. For example, SetVar takes as the first argument
  55 (before the =) a variable name, so:
  56
  57 ;exten => 1,2,SetVar,koko=lala
  58 ;exten => 1,3,SetVar,${koko}=blabla
  59
  60 stores to the variable "koko" the value "lala" and to variable "lala" the
  61 value "blabla".
  62
  63 In fact, everything contained ${here} is just replaced with the value of
  64 the variable "here".
  65
  66 EXPRESSIONS:
  67
  68 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is
  69 considered as an expression and it is evaluated. Evaluation works similar to
  70 (but is done on a later stage than) variable substitution: the expression
  71 (including the square brackets) is replaced by the result of the expression
  72 evaluation. The arguments and operands of the expression MUST BE separated
  73 with spaces (take care NOT to leave ANY spaces between opening and closing
  74 square brackets and the first and last arguments).
  75
  76 For example, after the sequence:
  77
  78 exten => 1,1,SetVar,"lala=$[1 + 2]";
  79 exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
  80
  81 the value of variable koko is "6".
  82
  83 Operators are listed below in order of increasing precedence.  Operators
  84 with equal precedence are grouped within { } symbols.
  85
  86      expr1 | expr2
  87              Return the evaluation of expr1 if it is neither an empty string
  88              nor zero; otherwise, returns the evaluation of expr2.
  89
  90      expr1 & expr2
  91              Return the evaluation of expr1 if neither expression evaluates to
  92              an empty string or zero; otherwise, returns zero.
  93
  94      expr1 {=, >, >=, <, <=, !=} expr2
  95              Return the results of integer comparison if both arguments are
  96              integers; otherwise, returns the results of string comparison
  97              using the locale-specific collation sequence.  The result of each
  98              comparison is 1 if the specified relation is true, or 0 if the
  99              relation is false.
 100
 101      expr1 {+, -} expr2
 102              Return the results of addition or subtraction of integer-valued
 103              arguments.
 104
 105      expr1 {*, /, %} expr2
 106              Return the results of multiplication, integer division, or
 107              remainder of integer-valued arguments.
 108
 109      expr1 : expr2
 110              The `:' operator matches expr1 against expr2, which must be a
 111              regular expression.  The regular expression is anchored to the
 112              beginning of  the string with an implicit `^'.
 113
 114              If the match succeeds and the pattern contains at least one regu-
 115              lar expression subexpression `\(...\)', the string correspond-
 116              ing to `\1' is returned; otherwise the matching operator
 117              returns the number of characters matched.  If the match fails and
 118              the pattern contains a regular expression subexpression the null
 119              string is returned; otherwise 0.
 120
 121 Parentheses are used for grouping in the usual manner.
 122
 123 The parser must be parsed with bison (bison is REQUIRED - yacc cannot
 124 produce pure parsers, which are reentrant)
 125
 126 CONDITIONALS
 127
 128 There is one conditional operator - the conditional goto :
 129
 130 ;exten => 1,2,gotoif,condition?label1:label2
 131
 132 If condition is true go to label1, else go to label2. Labels are interpreted
 133 exactly as in the normal goto command.
 134
 135 "condition" is just a string. If the string is empty or "0", the condition
 136 is considered to be false, if it's anything else, the condition is true.
 137 This is designed to be used together with the expression syntax described
 138 above, eg :
 139
 140 exten => 1,2,gotoif,$[${CALLERID} = 123456]?2|1:3|1
 141
 142
 143 Example of use :
 144
 145 exten => s,2,SetVar,"vara=1"
 146 exten => s,3,SetVar,"varb=$[${vara} + 2]"
 147 exten => s,4,SetVar,"varc=$[${varb} * 2]"
 148 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
 149