Extensions
The term extension can sometimes be misleading. In the traditional PBX environment, an extension is simply a phone connected to the phone system, typically with a three-digit or four-digit extension number. In FreeSWITCH an extension is actually a set of instructions that define what to do with a call. It can be as simple as dialing a three-digit or four-digit number, and having someone's desk phone ring. In fact, this is precisely what we did in Chapter 4, SIP and The User Directory, in the Adding a user section, when we added a new user and a corresponding extension to allow her phone to be dialed.
An extension definition begins with an <extension> tag and ends with a closing </extension> tag. All the conditions, actions, and anti-actions in between are part of the extension definition. Extensions have two optional attributes: name and continue. The name attribute is used primarily to keep your Dialplan readable. You can imagine how difficult it would be to look at a Dialplan file with dozens of <extension> tags without any names. The continue attribute determines the Dialplan parser's behavior when it finds a matching extension. An extension is said to match if all of the conditions for that extension evaluate to true. By default, extensions do not continue after the first Dialplan match. Setting continue="true" will cause the parser to keep looking for more extensions to match (see the How Dialplan Processing works section later in this chapter).
Conditions
Conditions decide the requirements to take the actions listed inside an extension. For example, you might have a condition that says "When 999 is dialed" and then runs the actions within the extension block. Keep in mind that conditions are not limited just to which phone number was dialed. Conditions can also be based on date and time, caller ID, the IP address of the sending server, and even channel variables. Looking through the example Dialplan files, you will mostly see conditions like the following:
<condition field="destination_number" expression="^(1234)$">
The destination_number field is by far the most common field tested, as most of the time we need to route a call based upon the digits dialed by a user.
Many extensions have just a single condition:
<extension name="Simple example">
<condition field="destination_number" expression="^(1234)$">
<!-- actions performed here -->
</condition>
</extension>
However, you can also stack conditions to create a logical AND, as shown in the following example:
<extension name="Two condition tags example">
<condition field="ani" expression="^(1111)$"></condition>
<condition field="destination_number" expression="^(1234)$">
<!-- actions performed here but only if both of the above
conditions are true -->
</condition>
</extension>
In the preceding example, both conditions must be true for the actions inside the second <condition> tag to be executed. The ani field (which is the calling party's phone number) must be "1111", and the dialed_number field must be "1234" for the actions to be executed. The plain-language description of this extension would be, "If the caller is 1111 and the destination is 1234 then execute these actions". Putting multiple <condition> tags inside a single extension is sometimes called stacking the conditions. Note that the first condition is still a valid XML node and requires a closing tag. XML allows a syntactic shortcut for this, which is as follows:
<condition field="ani" expression="^(1111)$"/>
The trailing / (forward slash) character closes the <condition> tag.
An additional feature of the <condition> tags is the break attribute. (Sometimes you will hear this being referred to as the break flag or break parameter.) When stacking multiple conditions, the break attribute can control how the parser behaves after each condition is evaluated. The break attribute can have the following four values:
on-true: Stop searching further conditions in this extension if the current condition is trueon-false: Stop searching further conditions in this extension if the current condition is false (this is the default)never: Keep searching further conditions regardless of whether the current condition is true or falsealways: Stop searching further conditions regardless of whether the current condition is true or false (very rarely used)
The default behavior is to break out of searching for more conditions as soon as the first failed match occurs. Let's try the same extension with a break attribute:
<extension name="Two condition tags example">
<condition field="ani" expression="^(1111)$" break="never">
<!-- actions performed here if caller is 1111 -->
</condition>
<condition field="destination_number" expression="^(1234)$">
<!-- actions performed here if caller dialed 1234 even if caller
was not 1111 -->
</condition>
</extension>
We added break="never" to the first condition. The parser will now behave differently when it gets to this condition. Regardless of whether or not the first condition fails, the parser moves on to the next condition within the same extension. Without the break="never" attribute, the parser would have stopped all further parsing of this extension, and moved on in the Dialplan. But what happens if this condition is true? The actions inside the first condition will be added to the task list, and then the parser moves on to the next condition in this extension. The net result is that we get a set of actions performed if the caller dialed 1234, but we have other actions that get performed if the caller happens to be 1111.
Tip
More advanced conditions are considered in Chapter 8, Advanced Dialplan Concepts.