Dialplan functions allow you to add more power to your expressions; you can think of them as intelligent variables. Dialplan functions allow you to calculate string lengths, dates and times, MD5 checksums, and so on, all from within a dialplan expression.
Dialplan functions have the following basic syntax:
FUNCTION_NAME
(argument
)
Much like 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.
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,n,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
. 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
core show functions
at the Asterisk command-line
interface. You can also look them up in Appendix F, Asterisk Manager Interface Actions.