channelvariables.tex

asterisk 是一个很有知名度开源软件

\section{Introduction}

There are two levels of parameter evaluation done in the Asterisk
dial plan in extensions.conf.
\begin{enumerate}
\item The first, and most frequently used, is the substitution of variable
  references with their values.
\item Then there are the evaluations of expressions done in \$[ .. ].
  This will be discussed below.
\end{enumerate}
Asterisk has user-defined variables and standard variables set
by various modules in Asterisk. These standard variables are
listed at the end of this document.

\section{Parameter Quoting}
\begin{astlisting}
\begin{verbatim}
exten => s,5,BackGround,blabla
\end{verbatim}
\end{astlisting}
The parameter (blabla) can be quoted ("blabla"). In this case, a
comma does not terminate the field. However, the double quotes
will be passed down to the Background command, in this example.

Also, characters special to variable substitution, expression evaluation, etc
(see below), can be quoted. For example, to literally use a \$ on the
string "\$1231", quote it with a preceding \textbackslash. Special characters that must
be quoted to be used, are [ ] \$ " \textbackslash. (to write \textbackslash itself, use \textbackslash).

These Double quotes and escapes are evaluated at the level of the
asterisk config file parser.

Double quotes can also be used inside expressions, as discussed below.

\section{Variables}

Parameter strings can include variables. Variable names are arbitrary strings.
They are stored in the respective channel structure.

To set a variable to a particular value, do:
\begin{astlisting}
\begin{verbatim}
    exten => 1,2,Set(varname=value)
\end{verbatim}
\end{astlisting}
You can substitute the value of a variable everywhere using \$\{variablename\}.
For example, to stringwise append \$lala to \$blabla and store result in \$koko,
do:
\begin{astlisting}
\begin{verbatim}
   exten => 1,2,Set(koko=${blabla}${lala})
\end{verbatim}
\end{astlisting}

There are two reference modes - reference by value and reference by name.
To refer to a variable with its name (as an argument to a function that
requires a variable), just write the name. To refer to the variable's value,
enclose it inside \$\{\}. For example, Set takes as the first argument
(before the =) a variable name, so:
\begin{astlisting}
\begin{verbatim}
  exten => 1,2,Set(koko=lala)
  exten => 1,3,Set(${koko}=blabla)
\end{verbatim}
\end{astlisting}
stores to the variable "koko" the value "lala" and to variable "lala" the
value "blabla".

In fact, everything contained \$\{here\} is just replaced with the value of
the variable "here".

\section{Variable Inheritance}

Variable names which are prefixed by "\_" will be inherited to channels
that are created in the process of servicing the original channel in
which the variable was set.  When the inheritance takes place, the
prefix will be removed in the channel inheriting the variable.  If the
name is prefixed by "\_\_" in the channel, then the variable is
inherited and the "\_\_" will remain intact in the new channel.

In the dialplan, all references to these variables refer to the same
variable, regardless of having a prefix or not.  Note that setting any
version of the variable removes any other version of the variable,
regardless of prefix.

\subsection{Example}
\begin{astlisting}
\begin{verbatim}
Set(__FOO=bar) ; Sets an inherited version of "FOO" variable
Set(FOO=bar)   ; Removes the inherited version and sets a local
               ; variable.
\end{verbatim}
\end{astlisting}

However, NoOp(\$\{\_\_FOO\}) is identical to NoOp(\$\{FOO\})

\section{Selecting Characters from Variables}

The format for selecting characters from a variable can be expressed as:
\begin{astlisting}
\begin{verbatim}
  ${variable_name[:offset[:length]]}
\end{verbatim}
\end{astlisting}
If you want to select the first N characters from the string assigned
to a variable, simply append a colon and the number of characters to
skip from the beginning of the string to the variable name.
\begin{astlisting}
\begin{verbatim}
  ; Remove the first character of extension, save in "number" variable
  exten => _9X.,1,Set(number=${EXTEN:1})
\end{verbatim}
\end{astlisting}
Assuming we've dialed 918005551234, the value saved to the 'number' variable
would be 18005551234. This is useful in situations when we require users to
dial a number to access an outside line, but do not wish to pass the first
digit.

If you use a negative offset number, Asterisk starts counting from the end
of the string and then selects everything after the new position. The following
example will save the numbers 1234 to the 'number' variable, still assuming
we've dialed 918005551234.
\begin{astlisting}
\begin{verbatim}
  ; Remove everything before the last four digits of the dialed string
  exten => _9X.,1,Set(number=${EXTEN:-4})
\end{verbatim}
\end{astlisting}
We can also limit the number of characters from our offset position that we
wish to use. This is done by appending a second colon and length value to the
variable name. The following example will save the numbers 555 to the 'number'
variable.
\begin{astlisting}
\begin{verbatim}
  ; Only save the middle numbers 555 from the string 918005551234
  exten => _9X.,1,Set(number=${EXTEN:5:3})
\end{verbatim}
\end{astlisting}
The length value can also be used in conjunction with a negative offset. This
may be useful if the length of the string is unknown, but the trailing digits
are. The following example will save the numbers 555 to the 'number' variable,
even if the string starts with more characters than expected (unlike the
previous example).
\begin{astlisting}
\begin{verbatim}
  ; Save the numbers 555 to the 'number' variable
  exten => _9X.,1,Set(number=${EXTEN:-7:3})
\end{verbatim}
\end{astlisting}
If a negative length value is entered, Asterisk will remove that many characters
from the end of the string.
\begin{astlisting}
\begin{verbatim}
  ; Set pin to everything but the trailing #.
  exten => _XXXX#,1,Set(pin=${EXTEN:0:-1})
\end{verbatim}
\end{astlisting}

\section{Expressions}

Everything contained inside a bracket pair prefixed by a \$ (like \$[this]) is
considered as an expression and it is evaluated. Evaluation works similar to
(but is done on a later stage than) variable substitution: the expression
(including the square brackets) is replaced by the result of the expression
evaluation.

For example, after the sequence:
\begin{astlisting}
\begin{verbatim}
exten => 1,1,Set(lala=$[1 + 2])
exten => 1,2,Set(koko=$[2 * ${lala}])
\end{verbatim}
\end{astlisting}
the value of variable koko is "6".

and, further:
\begin{astlisting}
\begin{verbatim}
exten => 1,1,Set,(lala=$[  1 +    2   ]);
\end{verbatim}
\end{astlisting}
will parse as intended. Extra spaces are ignored.


\subsection{Spaces Inside Variables Values}

If the variable being evaluated contains spaces, there can be problems.

For these cases, double quotes around text that may contain spaces
will force the surrounded text to be evaluated as a single token.
The double quotes will be counted as part of that lexical token.

As an example:

\begin{astlisting}
\begin{verbatim}
exten => s,6,GotoIf($[ "${CALLERID(name)}" : "Privacy Manager" ]?callerid-liar,s,1:s,7)
\end{verbatim}
\end{astlisting}

The variable CALLERID(name) could evaluate to "DELOREAN MOTORS" (with a space)
but the above will evaluate to:

\begin{verbatim}
"DELOREAN MOTORS" : "Privacy Manager"
\end{verbatim}

and will evaluate to 0.

The above without double quotes would have evaluated to:

\begin{verbatim}
DELOREAN MOTORS : Privacy Manager
\end{verbatim}

and will result in syntax errors, because token DELOREAN is immediately
followed by token MOTORS and the expression parser will not know how to
evaluate this expression, because it does not match its grammar.

\subsection{Operators}

Operators are listed below in order of increasing precedence.  Operators
with equal precedence are grouped within \{ \} symbols.

\begin{itemize}
  \item \verb!expr1 | expr2!

       Return the evaluation of expr1 if it is neither an empty string
       nor zero; otherwise, returns the evaluation of expr2.

  \item \verb!expr1 & expr2!

       Return the evaluation of expr1 if neither expression evaluates to
       an empty string or zero; otherwise, returns zero.

  \item \verb+expr1 {=, >, >=, <, <=, !=} expr2+

       Return the results of floating point comparison if both arguments are
       numbers; otherwise, returns the results of string comparison
       using the locale-specific collation sequence.  The result of each
       comparison is 1 if the specified relation is true, or 0 if the
       relation is false.

  \item \verb!expr1 {+, -} expr2!

       Return the results of addition or subtraction of floating point-valued
       arguments.

  \item \verb!expr1 {*, /, %} expr2!

       Return the results of multiplication, floating point division, or
       remainder of arguments.

  \item \verb!- expr1!

       Return the result of subtracting expr1 from 0.
       This, the unary minus operator, is right associative, and
       has the same precedence as the ! operator.

  \item \verb+! expr1+

       Return the result of a logical complement of expr1.
       In other words, if expr1 is null, 0, an empty string,
       or the string "0", return a 1. Otherwise, return a 0.
       It has the same precedence as the unary minus operator, and
       is also right associative.

  \item \verb!expr1 : expr2!

       The `:' operator matches expr1 against expr2, which must be a
       regular expression.  The regular expression is anchored to the
       beginning of  the string with an implicit `\^'.

       If the match succeeds and the pattern contains at least one regular
       expression subexpression `\(...\)', the string corresponing
       to `\textbackslash1' is returned; otherwise the matching operator
       returns the number of characters matched.  If the match fails and
       the pattern contains a regular expression subexpression the null
       string is returned; otherwise 0.

       Normally, the double quotes wrapping a string are left as part
       of the string. This is disastrous to the : operator. Therefore,
       before the regex match is made, beginning and ending double quote
       characters are stripped from both the pattern and the string.

   \item \verb!expr1 =~ expr2!

       Exactly the same as the ':' operator, except that the match is
       not anchored to the beginning of the string. Pardon any similarity
       to seemingly similar operators in other programming languages!
       The ":" and "=\~" operators share the same precedence.

   \item \verb!expr1 ? expr2 :: expr3!

       Traditional Conditional operator. If expr1 is a number
       that evaluates to 0 (false), expr3 is result of the this
       expression evaluation.  Otherwise, expr2 is the result.
       If expr1 is a string, and evaluates to an empty string,
       or the two characters (""), then expr3 is the
       result. Otherwise, expr2 is the result.  In Asterisk, all
       3 exprs will be "evaluated"; if expr1 is "true", expr2
       will be the result of the "evaluation" of this
       expression.  expr3 will be the result otherwise. This
       operator has the lowest precedence.
\end{itemize}

Parentheses are used for grouping in the usual manner.

Operator precedence is applied as one would expect in any of the C
or C derived languages.

\subsection{Floating Point Numbers}

In 1.6 and above, we shifted the \$[...] expressions to be calculated
via floating point numbers instead of integers. We use 'long double' numbers
when possible, which provide around 16 digits of precision with 12 byte numbers.

To specify a floating point constant, the number has to have this format: D.D, where D is
a string of base 10 digits. So, you can say 0.10, but you can't say .10 or 20.-- we hope
this is not an excessive restriction!

Floating point numbers are turned into strings via the '\%g'/'\%Lg' format of the printf
function set. This allows numbers to still 'look' like integers to those counting
on integer behavior. If you were counting on 1/4 evaluating to 0, you need to now say
TRUNC(1/4). For a list of all the truncation/rounding capabilities, see the next section.