DialPlan Component (Windows Embedded CE 6.0)

  • Article

1/6/2010

The dial plan defines a set of dialing rules to convert user dialed strings (from the Phone Application, Dialer or Contacts) into a format which is understood by the SIP server. Additionally the OEM can define a display string which is user friendly, can be used throughout the User Interface and is independent of the dial string used at the lower level.

A dial plan consists of a header and a set of rules.

Ee499317.collapse(en-US,WinEmbedded.60).gifDial Plan Header

The header can include a <host> tag which enables you to represent the address of the host server with a token (e.g. $host$). The token can be substituted for the host address in a rule. This facilitates updating the rules quickly when the host address changes. The $host$ token can be associated with one of the following:

  • An IP address. (for example, 192.168.50.9)
  • A domain name. (for example, fourthcoffee.com)
  • One of two predefined values:
    • #use_sipsrv_address# - Specifies that the host address is the address of the active SIP server (main or backup SIP server)
    • #use_sipsrv_host_name# - Specifies that the host address is the domain portion of the user’s URI (provisioned user account)

The following example shows a Dial Plan header:

<dialplan-header>
  <host>192.168.50.9</host>
</dialplan-header>

Ee499317.collapse(en-US,WinEmbedded.60).gifDial Plan Rule

Each rule consists of a pattern and one or more formatting templates. The pattern is a regular expression which specifies the set of strings that a user or network provided string will be compared against to find a match. A formatting template specifies the format of the string to be sent to the SIP server, or the format of the string to be displayed to the user. Possible formatting templates are:

  • “Dial”: Use this template to format the string into a URI which will be sent in the SIP INVITE. This template is optional. If it is not included in the rule then the phone number will be sent as entered.
  • “Display”: Use this template to format the string into what is displayed to the user in the phone applications. This template is optional. If it is not included in the rule then the phone number will be displayed as entered
  • “Transfer”: Use this template to format the string into what is sent in the “Refer-To:” header of a SIP REFER transaction. If this is not present, it is assumed that the “Dial” expression has the correct template.

Additionally, each rule can have a "restrict" clause. You can use the restrict clause to disallow calls made over VoIP, Cell or SMS (or all).

The following example shows a Dial Plan rule:

<rule pattern="(\d{1,3})\*(\d{1,3})\*(\d{1,3})\*(\d{1,3})" dial="\1.\2.\3.\4" display="\1.\2.\3.\4" restrict="Cell,SMS" />

The rule pattern indicates a match for strings, entered by the user, that consist of 4 groups of 1 to 3 numeric characters separated by asterisks (for example: "111*555*21*123", "127*0*0*1", etc). The dial and display templates convert the matched string to IP address format (for example '111.555.21.123') by specifying that the "match groups" should appear in the same order entered by the user and should be separated by a ".". For more information about Match groups see Dial Plan Dial Plan Regular Expression Engine - Language Summary. Finally the Restrict clause disallows cell or SMS calls.

Ee499317.collapse(en-US,WinEmbedded.60).gifAuto Dial Rule

Auto Dial rules specify numbers that should be dialed automatically. When a dial pattern that matches an Auto Dial rule is encountered the number is dialed without the user having to press the ‘dial’ button.

The Auto Dial option will only appear in the "Settings" menu if the Dial Plan contains one or more Auto Dial rules. The user must then select it from the "Settings" menu in order to enable Auto Dial.

The following example shows the structure of an Auto Dial rule:

<autodial prefix=”xxxx”  length=”xxxx” />

A valid dial string, for purposes of auto dialing, consists entirely of numeric characters.

The prefix attribute specifies the leading digits of the dial string.

The length attribute specifies the total length of the dial string, including the prefix digits.

prefix and length values must be numeric character strings.

A dial plan can contain multiple autodial rules.

The order of autodial rules in the XML file determines the priority order.

A dial string in an auto dial list is uniquely identified by its prefix, length and the relative order of its associated rule in a group of auto dial rules.

Ideally, for any entered dial string that matches an auto dial rule there should be a matching dial plan rule.

Ee499317.collapse(en-US,WinEmbedded.60).gifExample

The following example shows a complete Dial Plan

The 12 digit dialing rule (in bold) matches with the first auto-dial rule (also in bold) located at the end of the Dial Plan

<?xml version="1.0" encoding="utf-8" ?>
<!--
Copyright (c) Microsoft Corporation.  All rights reserved.
-->
<!--
Use of this source code is subject to the terms of the Microsoft end-user
license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
If you did not accept the terms of the EULA, you are not authorized to use
this source code. For a copy of the EULA, please see the LICENSE.RTF on your
install media.
-->
<dialplan xmlns='https://schemas.microsoft.com/embedded/VoIP'>
    <dialplan-header>
        <host>#use_sipsrv_host_name#</host>
    </dialplan-header>
    <!-- Dial Plan rules -->
    <!-- IP address rules -->
    <rule pattern='\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}'
        restrict='Cell,SMS'
        />
    <rule pattern='(\d{1,3})\*(\d{1,3})\*(\d{1,3})\*(\d{1,3})'
        dial='\1.\2.\3.\4'
        display='\1.\2.\3.\4'
        transfer='\1.\2.\3.\4'
        restrict='Cell,SMS'
        />
    <!-- 12-digits rules -->
    <rule pattern='91\s*-?\s*(\d{3})\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:9\1\2\3@$host$'
        display='1 (\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />

    <!-- 11-digits rules -->
    <rule pattern='1\s*-?\s*(\d{3})\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:91\1\2\3@$host$'
        display='1 (\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />
    <rule pattern='1\s*-?\s*\((\d{3})\)\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:91\1\2\3@$host$'
        display='1 (\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />
    <rule pattern='\+\s*1\s*-?\s*(\d{3})\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:91\1\2\3@$host$'
        display='+1 (\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />
    <rule pattern='\+\s*1\s*-?\s*\((\d{3})\)\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:91\1\2\3@$host$'
        display='+1 (\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />
    <rule pattern='9(\d{3})(\d{3})(\d{4})'
        dial='sip:9\1\2\3@$host$'
        display='(\1) \2-\3'
        transfer='sip:1\1\2\3@$host$'
        />

    <!-- 10-digits rules -->
    <rule pattern='(\d{3})\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:9\1\2\3@$host$'
        display='(\1) \2-\3'
        transfer='sip:\1\2\3@$host$'
        />
    <rule pattern='\((\d{3})\)\s*(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:9\1\2\3@$host$'
        display='(\1) \2-\3'
        transfer='sip:\1\2\3@$host$'
        />
    <rule pattern='(\d{3})\s*-?(\d{3})\s*-?\s*(\d{4})(\s*[Xx]\s*\d+)?'
        dial='sip:9\1\2\3@$host$'
        display='(\1) \2-\3'
        transfer='sip:\1\2\3@$host$'
        />
    <!-- 8-digits rules -->
    <rule pattern='9(\d{3})(\d{4})'
        dial='sip:9\1\2@$host$'
        display='\1-\2'
        transfer='sip:9\1\2@$host$'
        />

    <!-- 7-digits rules -->
    <rule pattern='(\d{3})\s*-?\s*(\d{4})'
        dial='sip:9425\1\2@$host$'
        display='\1-\2'
        transfer='sip:425\1\2@$host$'
        />
    <!-- SIP URI rules -->
    <rule pattern='[Ss][Ii][Pp][Ss]?:\s*9(\d{3})(\d{3})(\d{4})@(.+)'
        display='(\1) \2-\3'
        restrict='Cell,SMS'
        />
    <rule pattern='[Ss][Ii][Pp][Ss]?:\s*1(\d{3})(\d{3})(\d{4})@(.+)'
        display='(\1) \2-\3'
        restrict='Cell,SMS'
        />
    <rule pattern='[Ss][Ii][Pp][Ss]?:\s*(\d{3})(\d{3})(\d{4})@(.+)'
        display='(\1) \2-\3'
        restrict='Cell,SMS'
        />
   <rule pattern='([Ss][Ii][Pp][Ss]?:)?\s*([a-zA-Z0-9_-]+)@(.+)'
        display='\2'
        restrict='Cell,SMS'
        />
    <rule pattern='[Ss][Ii][Pp][Ss]?:\s*([^@]+)'
        display='\1'
        restrict='Cell,SMS'
        />
    <!-- 5-digits rules -->
    <rule pattern='(\d{3})-?(\d{2})'
        dial='sip:\1\2@$host$'
        display='\1\2'
        transfer='sip:\1\2@$host$'
        />
    <rule pattern='1\s*\((\d{3})\)\s*(\d)'
        dial='sip:1\1\2@$host$'
        display='1\1\2'
        transfer='sip:1\1\2@$host$'
        />
    <!-- AutoDial rules -->
    <autodial prefix='91'   length='12' />
    <autodial prefix='9206' length='11' />
    <autodial prefix='9425' length='11' />
    <autodial prefix='9'    length='8'  />
    <autodial prefix='1'    length='11' />
    <autodial prefix=''     length='5'  />

</dialplan>

See Also

Concepts

IP Phone Suite
VoIP Application Development

Other Resources

Voice over IP Phone Services