6.2. Dialplan
Functions
Dialplan functions
are not a new concept. In Asterisk 1.2, they should be used where
possible. Many applications that perform the same operation as a
corresponding function will eventually be removed in favor of the
function. Functions allow you to add more power to your
expressionsyou can think of them as being similar to operators, but
more advanced. For example, dialplan functions allow you to
calculate string lengths, dates and times, MD5 checksums, and so
on, all from within a dialplan expression.
6.2.1. Syntax
Dialplan functions have the following basic
syntax:
FUNCTION_NAME(argument)
Much like with variables, you reference a
function's name as above, but you
reference a function's value with
the addition of a dollar sign, an opening curly brace, and a
closing curly brace:
${FUNCTION_NAME(argument)}
Functions can also encapsulate other functions,
like so:
${FUNCTION_NAME(${FUNCTION_NAME(argument)})}
^ ^ ^ ^ ^^^^
1 2 3 4 4321
As you've probably already figured out, you must
be very careful about making sure you have matching parentheses and
braces. In the above example, we have labeled the opening
parentheses and curly braces with numbers and their corresponding
closing counterparts with the same numbers.
6.2.2. Examples of Dialplan
Functions
Functions are often used in conjunction with the
Set( ) application to either get or set the value of a
variable. As a simple example, let's look at the LEN( )
function. This function calculates the string length of its
argument. Let's calculate the string length of a variable and read
back the length to the caller:
exten => 123,1,Set(TEST=example)
exten => 123,2,SayNumber(${LEN(${TEST})})
The above example would evaluate the string
example as having seven characters, assign the number of
characters to the variable length, and then speak the number to the
user with the SayNumber( ) application.
Let's look at another simple example. If we
wanted to set one of the various channel timeouts, we could use the
TIMEOUT( ) function. The TIMEOUT( ) function
accepts one of three arguments: absolute, digit,
and response. Their corresponding applications are
AbsoluteTimeout( ), DigitTimeout( ), and
ResponseTimeout( ). To set the digit timeout with the
TIMEOUT( ) function, we could use the Set( )
application, like so:
exten => s,1,Set(TIMEOUT(digit)=30)
Notice the lack of ${ } surrounding the
function. Just as if we were assigning a value to a variable, we
assign a value to a function without the use of the ${ }
encapsulation.
A complete list of available functions can be
found by typing show functions at the Asterisk
command-line interface. |