{toc}
h1. Example Dialing Rules
In the examples below copy the *Phone pattern regular expression* and *Translation regular expression* to the corresponding fields of the *Edit Phone Number Dialing Rule* dialog and replace the phone numbers in the patterns with your own.
{color:red}*_IMPORTANT NOTE_*:{color}{color:maroon} If you copy and paste the rules in the dialing rules edit box make sure that extra space characters are not accidentally added at the beginning or end of the regular expressions.{color}
|| Name || Description || Example phone number(s) || Phone pattern regular expression || Translation regular expression || Translation result ||
| Extension Only | Keeps only the extension in the given phone number. | \+1 (222) 333-4444 Ext. 555 \\ \\ | {nl:^\\+1 \\(222\\) 333-4444 Ext. (\\d\{3\})$} \\ | $1 \\ \\ | 555 \\ \\ |
| | | \+1 (222) 333-4444 Ext. 55555 | {nl:^\\+1 \\(222\\) 333-4444 \\w+\\.? ?(\\d\{3,5\})$} | $1 | 55555 |
| SIP trunk \\ | Assumes long distance dialing for non 613 area codes but does not add 1 to satisfy SIP trunk provider. | \+1 (222) 333-4444 \\
\\ | {nl:^\\+1 \\(?(?\!613)(\\d\{3\})\\)? ?(\\d\{3\})\\-?(\\d\{4\})$} | 9$1$2$3 | 92223334444 \\ |
| | | \+1 (613) 333-4444 | \\ | \\ | No match, Windows dialing rules, if any, apply. |
| Calling France from Canada 1 | For numbers that start with the France Country Code, prefix with 011 | \+33 57 123345 | {nl:^\\+?33 (\\d\{2\}) ?(\\d\{6\})$} | 01133$1$2 | 0113357123345 |
| Calling France from Canada 2 | For numbers that start with the France Country Code, prefix with 9 011 | \+33 57 123345 | {nl:^\\+?33 (\\d\{2\}) ?(\\d\{6\})$} | 901133$1$2 | 90113357123345 |
| Local Dial Out | Adds the dial out prefix 9. | \+1 (222) 333-4444 \\
222.333.4444 \\
222-333-4444 | {nl:^(?:\\+?1 )?\\(?(\\d\{3\})?[\\)\\.-]? ?(\\d\{3\})[\\. \\-]?(\\d\{4\})$} | 9$1$2$3 | 92223334444 \\
92223334444 \\
92223334444 |
| No area/city code for local calls |Microsoft's telephony services fails to apply dialing rules for local UK calls. This rule removes the area code and prefixes the number with 9 to dial out local calls. Replace the leading 9 with your dial out code and 01899 with your area code.|01234 123 456 \\
012340123456 \\
01899 01234123456|^(?:{nl:\\+}?\d\{1,3\} )?(?:01899 )?(\d\{5\}){nl:[\\-} \.{nl:]}?(\d\{3\}){nl:[\\-} \.{nl:]}?(\d\{3\})$|9$1$2$3|901234123456|
| Long Distance Dial Out | Adding "9 1" as a prefix for phone numbers in area codes 222, 777, and 888. | 222.333.4444 \\
(777) 333-4444 \\
\+1 (888) 333-4444 | {nl:^(?:\\+?1 )?\\(?(222|777|888)[\\) \\.\\-]+(\\d\{3\})[\\.\\- ](\\d\{4\})$} | 91$1$2$3 | 912223334444 \\
917773334444 \\
918883334444 |
h1. About Dialing Rules
The application makes use of two different kinds of dialing rules: Windows Telephony dialing rules, and user defined dialing rules. These rules can be used together or separately.
As a rule of thumb use Windows Telephony Dialing rules first as they follow dialing plans set forth by the International Telecommunications Union (ITU) and by the individual countries themselves.
Create your own dialing rules when you need to translate a number for a different reason or when the Windows Telephony Rules do not give the expected results.
h2. Windows Telephony Rules
Microsoft Windows Telephony offers dialing rules which correspond to international dialing rules and location rules the user can configure through *Phone and Modem Options* in the Control Panel. To use these rules enable them through the settings dialog on the General tab.
h2. User Defined Rules
Dialing rules can be defined by the user to ensure certain phone numbers are dialed in a specific manner. For example, the phone numbers of your office colleagues are stored in the corporate directory or Outlook Contacts using the full company phone number followed by a phone extension ({nl:e.g.} (444) 555-6666 x7777). When the application encounters such a number it starts by dialing the main phone number and, once the call is established, offers the user to dial the extension. Obviously this will not work for calling colleagues on the same phone system. You can change this behavior by creating a dialing rule that forces IOC to just dial the phone extension.
h3. Translating Phone Numbers
Translating a phone number requires 2 regular expressions:
The first one, called *the phone pattern regular expression*, is used to match the phone number.
The second, called *the translation pattern regular expression*, is used to substitute part or all of the matched phone number with the dialing rule requirements.
The following table shows a couple of sample translations:
|| Example phone number(s) || Phone pattern regular expression || Translation regular expression || Translation result ||
| 555-6666 | \^(\d\{3\})\-(\d\{4\})$ | $1$2 | 5556666 |
| 444-555-6666 \\
333-555-6666 | \^(444\|333)\-(\d\{3\})\-(\d\{4\})$ | 8 1$1$2$3 | 8 14445556666 \\
8 13335556666 |
h2. How Dialing Rules are Applied
When rules are applied:
* Search for the first user defined rule that matches the number.
** If match is not found:
*** If Windows Telephony Rules are not selected:
**** Number is dialed as is.
** If match is found:
*** Rule is applied and translated number is dialed.
** Otherwise number is converted to canonical format, asking user for input if necessary.
*** Search for user rule that matches canonical form
**** If match is found:
***** Rule is applied and translated number is dialed.
**** Otherwise Windows Telephony Rules are applied and translated number is dialed.
h1. Help with regular expressions
h2. What are regular expressions
[Regular expressions|http://en.wikipedia.org/wiki/Regular_expression] are a rather complex concept. For the purpose of dialing rules they are used to match phone numbers and modify them. The application uses the [Microsoft .NET regular expression engine|http://msdn2.microsoft.com/en-us/library/az24scfc(VS.71).aspx].
h2. Bare Essentials
The following sections provide an incomplete reference of regular expression syntax. What is provided is the strict minimum needed for the purpose of matching phone numbers and translating them into a specific dialable form. Please refer to [Wikipedia|http://en.wikipedia.org/wiki/Regular_expression] and to the [Microsoft .Net Regular Expression reference material|http://msdn2.microsoft.com/en-us/library/az24scfc(VS.71).aspx] for further understanding of regular expressions.
h3. Special Characters
Regular expressions use a number of characters as matching instructions {nl:('.', '-', '+', '*', '?', '(', ')', '[', ']', '\{', '\}', '|', '$')}. If you need to match one of these characters you need to prefix (escape) them with a backslash ('\').
{code}
The expression "\(444\) 555-6666" matches the string "(444) 555-6666"
{code}
h3. Quantifiers
|| Quantifier || Description ||
| \* | Match preceding character zero or more times. (35\* matches 3, 35, 355, 3555, ...) |
| + | Match preceding character one or more times. (35\+ matches 35, 355, 3555, ...) |
| ? | Match preceding character zero or one times. (35? matches 3 and 35) |
| \{n\} | Specifies exactly n matches; for example, (pizza)\{2\}. |
| \{n,\} | Specifies at least n matches; for example, (abc)\{2,\}. |
| \{n,m\} | Specifies at least n, but no more than m, matches. |
h3. Character Classes
|| Character class || Description ||
| . | Matches any character |
| {nl:[aeiou]} | Matches any single character included in the specified set of characters. |
| {nl:[^aeiou]} | Matches any single character not in the specified set of characters. |
| {nl:[0-9a-fA-F]} | Use of a hyphen "-" allows specification of contiguous character ranges. |
| \w | Matches any word character. \w is equivalent to {nl:[a-zA-Z_0-9]}. |
| \W | Matches any non word character. \W is equivalent to {nl:[^a-zA-Z_0-9]}. |
| \s | Matches any white-space character. |
| \S | Matches any non-white-space character. |
| \d | Matches any decimal digit. Equivalent to {nl:[0-9]} |
| \D | Matches any non digit. Equivalent to {nl:[^0-9]} |
h3. Grouping
|| Grouping construct || Description ||
| ( ) | Captures the matched substring |
| (?: ) | Non-capturing group. |
h3. Alternating
|| Alternation construct || Definition ||
| \| | Matches any one of the terms separated by the "\|" (vertical bar) character; for example, cat\|dog\|tiger. The leftmost successful match wins. |
h3. Substitution
|| Character || Description ||
| $number | Substitutes the last substring matched by group number number (decimal)({nl:e.g. $1}). |
h3. Find vs Match
Regular expressions can be used to find certain patterns within a string or they can be used to validate that a whole string conforms to a specific pattern. The dialing rules engine performs a match instead of a find. In this context, it is much easier to write and test dialing rules if the phone pattern starts with the '^' character, which indicates that the following characters must match the beginning of the string, and ends with '$', which indicates that the preceding characters must match the end of the string. As you will see in the examples, all phone pattern regular expressions will follow this design.
h1. Example Dialing Rules
In the examples below copy the *Phone pattern regular expression* and *Translation regular expression* to the corresponding fields of the *Edit Phone Number Dialing Rule* dialog and replace the phone numbers in the patterns with your own.
{color:red}*_IMPORTANT NOTE_*:{color}{color:maroon} If you copy and paste the rules in the dialing rules edit box make sure that extra space characters are not accidentally added at the beginning or end of the regular expressions.{color}
|| Name || Description || Example phone number(s) || Phone pattern regular expression || Translation regular expression || Translation result ||
| Extension Only | Keeps only the extension in the given phone number. | \+1 (222) 333-4444 Ext. 555 \\ \\ | {nl:^\\+1 \\(222\\) 333-4444 Ext. (\\d\{3\})$} \\ | $1 \\ \\ | 555 \\ \\ |
| | | \+1 (222) 333-4444 Ext. 55555 | {nl:^\\+1 \\(222\\) 333-4444 \\w+\\.? ?(\\d\{3,5\})$} | $1 | 55555 |
| SIP trunk \\ | Assumes long distance dialing for non 613 area codes but does not add 1 to satisfy SIP trunk provider. | \+1 (222) 333-4444 \\
\\ | {nl:^\\+1 \\(?(?\!613)(\\d\{3\})\\)? ?(\\d\{3\})\\-?(\\d\{4\})$} | 9$1$2$3 | 92223334444 \\ |
| | | \+1 (613) 333-4444 | \\ | \\ | No match, Windows dialing rules, if any, apply. |
| Calling France from Canada 1 | For numbers that start with the France Country Code, prefix with 011 | \+33 57 123345 | {nl:^\\+?33 (\\d\{2\}) ?(\\d\{6\})$} | 01133$1$2 | 0113357123345 |
| Calling France from Canada 2 | For numbers that start with the France Country Code, prefix with 9 011 | \+33 57 123345 | {nl:^\\+?33 (\\d\{2\}) ?(\\d\{6\})$} | 901133$1$2 | 90113357123345 |
| Local Dial Out | Adds the dial out prefix 9. | \+1 (222) 333-4444 \\
222.333.4444 \\
222-333-4444 | {nl:^(?:\\+?1 )?\\(?(\\d\{3\})?[\\)\\.-]? ?(\\d\{3\})[\\. \\-]?(\\d\{4\})$} | 9$1$2$3 | 92223334444 \\
92223334444 \\
92223334444 |
| No area/city code for local calls |Microsoft's telephony services fails to apply dialing rules for local UK calls. This rule removes the area code and prefixes the number with 9 to dial out local calls. Replace the leading 9 with your dial out code and 01899 with your area code.|01234 123 456 \\
012340123456 \\
01899 01234123456|^(?:{nl:\\+}?\d\{1,3\} )?(?:01899 )?(\d\{5\}){nl:[\\-} \.{nl:]}?(\d\{3\}){nl:[\\-} \.{nl:]}?(\d\{3\})$|9$1$2$3|901234123456|
| Long Distance Dial Out | Adding "9 1" as a prefix for phone numbers in area codes 222, 777, and 888. | 222.333.4444 \\
(777) 333-4444 \\
\+1 (888) 333-4444 | {nl:^(?:\\+?1 )?\\(?(222|777|888)[\\) \\.\\-]+(\\d\{3\})[\\.\\- ](\\d\{4\})$} | 91$1$2$3 | 912223334444 \\
917773334444 \\
918883334444 |
h1. About Dialing Rules
The application makes use of two different kinds of dialing rules: Windows Telephony dialing rules, and user defined dialing rules. These rules can be used together or separately.
As a rule of thumb use Windows Telephony Dialing rules first as they follow dialing plans set forth by the International Telecommunications Union (ITU) and by the individual countries themselves.
Create your own dialing rules when you need to translate a number for a different reason or when the Windows Telephony Rules do not give the expected results.
h2. Windows Telephony Rules
Microsoft Windows Telephony offers dialing rules which correspond to international dialing rules and location rules the user can configure through *Phone and Modem Options* in the Control Panel. To use these rules enable them through the settings dialog on the General tab.
h2. User Defined Rules
Dialing rules can be defined by the user to ensure certain phone numbers are dialed in a specific manner. For example, the phone numbers of your office colleagues are stored in the corporate directory or Outlook Contacts using the full company phone number followed by a phone extension ({nl:e.g.} (444) 555-6666 x7777). When the application encounters such a number it starts by dialing the main phone number and, once the call is established, offers the user to dial the extension. Obviously this will not work for calling colleagues on the same phone system. You can change this behavior by creating a dialing rule that forces IOC to just dial the phone extension.
h3. Translating Phone Numbers
Translating a phone number requires 2 regular expressions:
The first one, called *the phone pattern regular expression*, is used to match the phone number.
The second, called *the translation pattern regular expression*, is used to substitute part or all of the matched phone number with the dialing rule requirements.
The following table shows a couple of sample translations:
|| Example phone number(s) || Phone pattern regular expression || Translation regular expression || Translation result ||
| 555-6666 | \^(\d\{3\})\-(\d\{4\})$ | $1$2 | 5556666 |
| 444-555-6666 \\
333-555-6666 | \^(444\|333)\-(\d\{3\})\-(\d\{4\})$ | 8 1$1$2$3 | 8 14445556666 \\
8 13335556666 |
h2. How Dialing Rules are Applied
When rules are applied:
* Search for the first user defined rule that matches the number.
** If match is not found:
*** If Windows Telephony Rules are not selected:
**** Number is dialed as is.
** If match is found:
*** Rule is applied and translated number is dialed.
** Otherwise number is converted to canonical format, asking user for input if necessary.
*** Search for user rule that matches canonical form
**** If match is found:
***** Rule is applied and translated number is dialed.
**** Otherwise Windows Telephony Rules are applied and translated number is dialed.
h1. Help with regular expressions
h2. What are regular expressions
[Regular expressions|http://en.wikipedia.org/wiki/Regular_expression] are a rather complex concept. For the purpose of dialing rules they are used to match phone numbers and modify them. The application uses the [Microsoft .NET regular expression engine|http://msdn2.microsoft.com/en-us/library/az24scfc(VS.71).aspx].
h2. Bare Essentials
The following sections provide an incomplete reference of regular expression syntax. What is provided is the strict minimum needed for the purpose of matching phone numbers and translating them into a specific dialable form. Please refer to [Wikipedia|http://en.wikipedia.org/wiki/Regular_expression] and to the [Microsoft .Net Regular Expression reference material|http://msdn2.microsoft.com/en-us/library/az24scfc(VS.71).aspx] for further understanding of regular expressions.
h3. Special Characters
Regular expressions use a number of characters as matching instructions {nl:('.', '-', '+', '*', '?', '(', ')', '[', ']', '\{', '\}', '|', '$')}. If you need to match one of these characters you need to prefix (escape) them with a backslash ('\').
{code}
The expression "\(444\) 555-6666" matches the string "(444) 555-6666"
{code}
h3. Quantifiers
|| Quantifier || Description ||
| \* | Match preceding character zero or more times. (35\* matches 3, 35, 355, 3555, ...) |
| + | Match preceding character one or more times. (35\+ matches 35, 355, 3555, ...) |
| ? | Match preceding character zero or one times. (35? matches 3 and 35) |
| \{n\} | Specifies exactly n matches; for example, (pizza)\{2\}. |
| \{n,\} | Specifies at least n matches; for example, (abc)\{2,\}. |
| \{n,m\} | Specifies at least n, but no more than m, matches. |
h3. Character Classes
|| Character class || Description ||
| . | Matches any character |
| {nl:[aeiou]} | Matches any single character included in the specified set of characters. |
| {nl:[^aeiou]} | Matches any single character not in the specified set of characters. |
| {nl:[0-9a-fA-F]} | Use of a hyphen "-" allows specification of contiguous character ranges. |
| \w | Matches any word character. \w is equivalent to {nl:[a-zA-Z_0-9]}. |
| \W | Matches any non word character. \W is equivalent to {nl:[^a-zA-Z_0-9]}. |
| \s | Matches any white-space character. |
| \S | Matches any non-white-space character. |
| \d | Matches any decimal digit. Equivalent to {nl:[0-9]} |
| \D | Matches any non digit. Equivalent to {nl:[^0-9]} |
h3. Grouping
|| Grouping construct || Description ||
| ( ) | Captures the matched substring |
| (?: ) | Non-capturing group. |
h3. Alternating
|| Alternation construct || Definition ||
| \| | Matches any one of the terms separated by the "\|" (vertical bar) character; for example, cat\|dog\|tiger. The leftmost successful match wins. |
h3. Substitution
|| Character || Description ||
| $number | Substitutes the last substring matched by group number number (decimal)({nl:e.g. $1}). |
h3. Find vs Match
Regular expressions can be used to find certain patterns within a string or they can be used to validate that a whole string conforms to a specific pattern. The dialing rules engine performs a match instead of a find. In this context, it is much easier to write and test dialing rules if the phone pattern starts with the '^' character, which indicates that the following characters must match the beginning of the string, and ends with '$', which indicates that the preceding characters must match the end of the string. As you will see in the examples, all phone pattern regular expressions will follow this design.