IP Phone Suite Provisioning Examples (Windows Embedded CE 6.0)
1/6/2010
The following examples illustrate how to provision VoIP settings.
Query Example
Input XML:
<voip-provision>
<set name="SIPSettings" value="XXXX" />
<query name="VoicemailSettings" />
</voip-provision>
Output XML:
<voip-provision>
<query name="VoicemailSettings" value="5555551212" />
</voip-provision>
Provisioning SIP Settings Example
The following example shows how to provision SIP settings for more information about provisioning SIP settings see SIP Server Settings:
<voip-provision>
<set name="SIPsettings"
value="<provision key='1232ab01' name='YamazakiVoIP'>
<user account='example\useraccount' password='test'
uri='sip:user@example.com'
allowedauth='digest'/>
<sipsrv addr='1.2.3.4' protocol='UDP'role='proxy'>
<session party='First' type='pc2pc' />
<session party='First' type='pc2ph' />
</sipsrv>
<sipsrv addr='1.2.3.4'
protocol='UDP'role='registrar'/>
</provision>" />
/>
</voip-provision>
Provisioning the Dialplan Component Example
The following example shows how to provision Dialplan settings. For more information about the Dial Plan see "DialPlan Component":
<voip-provision>
<set name="DialPlan"
value="<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$' />
</dialplan>"
/>
</voip-provision>
Complete Provisioning Example
The following example shows a complete provisioning file:
<?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 your Microsoft Windows CE Source Alliance Program license form. If you did not accept the terms of such a license, you are not authorized to use this source code. -->
<voip-provision>
<set name="SIPsettings"
value="<provision key='1232ab01' name='YamazakiVoIP'>
<user account="example\useraccount' password='test'
uri='sip:5555551212@1.2.3.4'
allowedauth='digest'/>
<sipsrv addr='1.2.3.4' protocol='UDP'
role='proxy'>
<session party='First' type='pc2pc' />
<session party='First' type='pc2ph' />
</sipsrv>
<sipsrv addr='1.2.3.4' protocol='UDP'
role='registrar'/>
</provision>" />
<set name="VoicemailNumber" value="5551212" />
<set name="DialPlan"
value="<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:9555\1\2@$host$'
display='\1-\2'
transfer='sip:555\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='955' length='11' />
<autodial prefix='9' length='8' />
<autodial prefix='1' length='11' />
<autodial prefix='' length='5' />
</dialplan>"
/>
</voip-provision>
Configuring the Phone with Provisioning.xml
You can specify phone configuration settings in the provisioning.xml file. This XML file consists of a PHONE-CONFIGURATION element with one or more of the following elements, each specifying a category of configuration data:
- AdminMode: Settings for managing PINs
- DateTime: Settings for SNTP Server, Time Zone, and Daylight Saving Time
- CallPreference: Call Preferences
- IPConfig: Network settings
- ExServer: Exchange Server
- Line-Data: Settings for configuring individual VoIP lines
- DialPlan: Settings for the phone's Dial Plan
- Registry: Directly adding and removing registry values
- File: Copying and deleting files from the phone's file system
- Phone-Services: Enabling and disabling other phone services
.gif "Ee499272.collapse(en-US,WinEmbedded.60).gif")
AdminMode
The AdminMode element specifies the Personal Identification Numbers (PINs) used to authenticate the phone administrator and the phone's user.
- AdminPIN: A 4-10 digit number that is used as the password for changing phone administration settings. When someone attempts to edit a protected setting, the phone prompts for the Administrator PIN.
- UserPIN: A 4-10 digit number that provides the user PIN for the phone. This field is intended to allow a phone administrator to help a user unlock a phone in case the user forgets the PIN.
The following example shows how to specify attributes in the AdminMode element:
<category name="adminmode">
<Admin Pin="112233"/>
<User Pin="5678"/>
</category>
DateTime
The DateTime element specifies date and time settings such as the phone's time zone and the Daylight Savings Time (DST) period. The phone can compute the DST start and end dates in two ways: by using the "Day of Month" or the "Day and Week" method.
- The "Day of Month" method specifies a day of the month DST will start or end (for example, the 10th day of May).
- The "Day and Week" method specifies a week of the month and day of the week that DST will start or end (for example, Sunday of the 3rd week of April).
The DSTStart attributes indicate the start of Daylight Saving Time and the STDStart items indicate when standard time resumes (and DST ends).
Here is the complete list of DateTime attributes; where applicable, the valid value range is shown in parentheses:
- SNTPServer: The network path to the time server the phone will use to set its clock (for example, time.microsoft.com)
- TimeZone: The textual version of the phone's time zone. This should match one of the time zone descriptions stored in the registry (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Time Zones). For example, "(GMT-05:00) Eastern Time (US & Canada)". The first portion of the time zone description is used as the offset from GMT.
- AutoAdjustDST: (0/1). 1 indicates that the phone should automatically adjust itself for daylight saving time. 0 indicates that the phone will not, and none of the following settings are needed.
- DSTStartYear: The first year that the DST settings will be valid. (For example, the current DST settings are valid from 1995 to 2012.) For years outside the DST settings, the STD (Standard) settings are used.
- DSTStartMonth: (1-12). The index of the month that DST starts in. For example, 3 represents March.
- DSTStartDay: (0-31). The day of the month that DST starts in. If DST start is represented using the Day and Week approach, this value should be 0.
- DSTStartWeekOfMonth: (1-5). (Day and Week method only; disregarded for Day of Month method.) The week of the month that DST starts in.
- DSTStartDayOfWeek: (1-7). (Day and Week method only; disregarded for Day of Month method.) The day of the week that DST starts in.
- DSTStartHour: (0-23). The hour that DST starts in. For example, 2 represents 2:00am.
- STDStartYear: The last year that the DST settings will be valid. 0 indicates that they will not become invalid.
- STDStartMonth: (1-12)
- STDStartDay: (0-31)
- STDStartWeekOfMonth: (1-5)
- STDStartDayOfWeek: (1-7)
- STDStartHour: (0-23)
The following example shows how to specify attributes in the DateTime element:
<category name="datetime">
<SNTPServer>time.microsoft.com</SNTPServer>
<TimeZone>(GMT-05:00) Eastern Time (US & Canada)</TimeZone>
<AutoAdjustDST>1</AutoAdjustDST>
<DSTStartYear>1995</DSTStartYear>
<DSTStartMonth>3</DSTStartMonth>
<DSTStartDay>0</DSTStartDay>
<DSTStartWeekOfMonth>2</DSTStartWeekOfMonth>
<DSTStartDayOfWeek>1</DSTStartDayOfWeek>
<DSTStartHour>2</DSTStartHour>
<STDStartYear>2012</DSTStartYear>
<STDStartMonth>10</STDStartMonth>
<STDStartDay>0</STDStartDay>
<STDStartWeekOfMonth>2</STDStartWeekOfMonth>
<STDStartDayOfWeek>1</STDStartDayOfWeek>
<STDStartHour>2</STDStartHour>
</category>
CallPreference
The CallPreference element specifies default values for the following telephony features; the end user can override any of them:
- DoNotDisturb: (Enabled: 0/1). This determines whether the phone automatically rejects all incoming calls, typically sending them to voicemail.
- AutoAnswer: (Enabled: 0/1; WaitTime: 1/2/3/5/10; Tone: <FilePathName>). This determines whether the phone will automatically go off hook in speakerphone mode when there is an incoming call. WaitTime gives the delay (in seconds) before the phone goes off hook. Tone provides the sound that the phone should play before going off hook.
- BlockCallerID: (Enabled: 0/1). This determines whether the phone blocks outgoing caller ID information, using the SIP Privacy extensions.
- AnonCallBlock: (Enabled: 0/1). This determines whether the phone will reject all incoming calls that don't provide caller ID information.
- CallForwarding: (Enabled: 0/1). This determines whether the phone automatically forward incoming calls to another phone number.
- RingTones: (Tone: <FilePathName>). This determines the sound that the phone should play to indicate that there is an incoming call. The sound is played repeatedly.
- CallWaitTone: (Enabled: 0/1; Tone: <FilePathName>). This determines whether the phone supports call waiting. If so, Tone indicates the sound to play to alert the user that there is an incoming call (when the user is already engaged in an active call).
- MsgWaitTone: (Tone: <FilePathName>). This determines the sound to play to alert the user that there is a new voicemail message waiting for them.
The following example shows how to specify attributes in the CallPreference element:
<category name="callpreference">
<DoNotDisturb Enabled="0"/>
<AutoAnswer Enabled ="0" WaitTime="3" Tone="\Sounds\Alert\beep.wav"/>
<BlockCallerId Enabled="1"/>
<AnonCallBlock Enabled="0"/>
<CallForwarding Enabled="0"/>
<RingTones Tone="\Sounds\ring.wav"/>
<CallWaitTone Enabled="1" Tone="\Sounds\Alert\beep.wav"/>
<MsgWaitTone Tone="\Sounds\Alert\waiting.wav"/>
</category>
IPConfig
The IPConfig element specifies the following Internet Protocol (IP) settings:
- EnableDHCP: (0/1). 1 indicates that the phone should rely on a DHCP server to get its IP address, masks, gateway, and domain name servers. If the phone uses DHCP, the other IPConfig settings are ignored. 0 indicates that these values are static and that all of the following settings need to be provided.
- IPAddress: (#.#.#.#). The static IP Address (for example, 192.168.4.3) assigned to this phone.
- SubnetMask: (#.#.#.#). The bit mask (for example, 255.255.255.0) used to identify the subnet portion of the IP Address.
- DefaultGateway: (#.#.#.#). The node on the network that serves as a connection to the Internet.
- DNS: (Primary: #.#.#.#; Secondary: #.#.#.#). The primary and secondary servers used to translate hostnames into IP Addresses.
The following example shows how to specify attributes in the IPConfig element:
<category name="ipconfig">
<EnableDHCP>0</EnableDHCP>
<IPAddress>192.54.24.2</IPAddress>
<SubnetMask>255.255.255.0</SubnetMask>
<DefaultGateway>157.56.176.1</DefaultGateway>
<DNS Primary="157.54.14.146" Secondary="157.54.14.178"/>
</category>
ExServer
The ExServer element specifies Exchange Server settings:
- ExchangeServer: (<NetworkPathName>). Address of the Windows Exchange Server (for example, http://mail.thephone-company.com) to be used for Global Address List look-up and Free/Busy data for enterprise contacts.
- HTTPProxy: (<NetworkName>). The name of the HTTP Proxy used to access the network.
The following example shows how to specify attributes in the ExServer element:
<category name="exserver">
<ExchangeServer>http://mail.windows.microsoft.com</ExchangeServer>
<HTTPProxy>itgproxy</HTTPProxy>
</category>
Line-Data
The Line-Data element contains a set of line-data attributes, each containing the settings for a particular line on the phone. The VoIP sample application can support up to five lines in the UI, but the phone itself supports an arbitrary number of lines. Each line is made up of the following components:
- User: This field contains details of the SIP account used to register with the server. It contains the following sub-attributes:
- Account: The account name (user ID) used to register with the server
- Password: The password used to authenticate with the server
- Name: Caller ID (friendly name) that is sent with the SIP INVITE
- Realm: Authentication Domain used when the user's identity is challenged
- URI: The SIP URI that serves as the user's phone number
- Server: This field specifies how the phone should connect to the server. It contains the following sub-attributes:
- Proxy: (#.#.#.#). The IP Address for the proxy server.
- Backup-Proxy: (#.#.#.#). The IP Address for the backup proxy server.
- Registrar: (#.#.#.#). The IP Address for the registry server.
- Backup-Registrar: (#.#.#.#). The IP Address for the backup registry server.
- Voicemail-Proxy: (#.#.#.#). The IP Address for the proxy server used for voicemail.
- Sharing-Proxy: (#.#.#.#). The IP Address for the proxy-sharing proxy server (a proxy server that shares resources with other servers).
- Transport: A transport protocol, such as UDP.
- Services: This optional field provides information on how to connect to various services. It contains the following sub-attributes:
- Friendly-name: This short text string is used to identify this line in the Line Status Panel and in the Line Settings screen.
- Voicemail-number: The phone number used to access voicemail for this line. This can be a standard phone number or a SIP URI.
- Voicemail-type: (subscribe/unsolicited/none). How the line registers with the voicemail service. Subscribe specifies that the phone maintains an active subscription for Message-Waiting Indication (MWI) events. Unsolicited specifies that the server sends unsolicited updates whenever MWI status changes. None indicates that the line doesn't have MWI support.
- Park: (Park-Enabled: 0/1; Park-Collect-Input: 0/1; Park-URI: <FormatString>). Park-Enabled indicates whether Call Parking is enabled on this phone. Park-Collect-Input indicates whether the phone UI needs to prompt the user for a call parking address when parking a call. Park-URI is a format string (for example, "SIP:%s@thephone-company.com") that is used to get the SIP URI to forward a call to in order to park it. If Park-Collect-Input is 1, then this format string should accept a single string.
- Pickup: (Pickup-Enabled: 0/1; Pickup-URI-Format: <FormatString>). Pickup-Enabled indicates whether Call Pickup is enabled on this phone. Pickup-URI-Format is a format string (for example, "SIP:%s@thephone-company.com") that is used to get the SIP URI to call in order pick up a call. The format string should accept a single argument.
- Line-Type: (private/shared). A shared line is one that supports Shared Call Appearance. A private line is one that doesn't.
- Appearances: (<PositiveInteger>). The number of shared appearances that this line supports. This setting is only valid if Line-Type is set to shared.
The following example shows how to specify attributes in the Line-Data element:
<category name="line-data">
<line-data>
<line id="1">
<user account="sample" uri="sample@10.196.50.19"
password="test" />
<server proxy="10.196.50.19" registrar="10.196.50.19"
transport="udp" />
<services friendly-name="sample"
voicemail-number="msgsample@10.196.50.19"
voicemail-type="subscribe" />
</line>
</line-data>
</category>
DialPlan
The DialPlan element specifies the phone's dial plan, either by pointing to an XML file, or by providing the dial plan data in-line. By default, the phone looks for its dial plan at \windows\ipdialplan.xml. If the dial plan is stored at a different location, this category can be used to specify this location.
There are two methods that can be used to set a dial plan for the phone: including an in-line dial plan in the provisioning file and providing a file pathname to where it is located in the file system.
- DialPlanXML: (FileName: <FilePathName>). FileName provides a fully specified path to the XML file containing the dial plan. For information on dial plan format, see DialPlan Component.
The following example shows how to specify attributes in the DialPlan element, using the DialPlanXML attribute to specify a path to the data plan file:
<category name="dialplan">
<DialPlanXML filename="file:\\\windows\dialplan1.xml"/>
</category>
Alternatively, you can include the dial plan in-line in the DialPlan element. If so, you must escape-format all of the reserved XML characters such as "<" and ">" (for example, "<" and ">").
Registry
An OEM can provide access to additional settings without changing the XML schema for provisioning.xml, by storing the settings in the registry. A phone administrator can then set these values through the registry category. The category can specify an arbitrary number of actions, which are run sequentially from top to bottom.
Key: (Root: <HiveKey>; Path: <PathToTheNode>). Root and Path combine to locate the node in the registry where the actions are to be taken. If the specified node does not already exist, it is created.
Note
For security reasons, the application restricts Root to "HKLM" and Path to "system\state\VoIP", "system\VoIP" or "comm\RTC".
- Set: (Name <NameOfRegistryValue>; Type (dw/sz); Value: <DataToBeStored>). This writes a value to the registry, overwriting any existing value. "dw" specifies a DWord value and "sz" specifies a String value.
- Delete: (Name). This action removes a setting value from the registry.
The following example shows how to specify attributes in the Registry element:
<category name="registry">
<key root="HKLM" path="System\State\VoIP">
<set name="SampleDword" type="dw" value="20000" />
<set name="SampleString" type="sz" value="Hello" />
<delete name="DeleteMe" />
</key>
<delete root="HKCU" path="System\VoIP\Remove" />
</category>
File
A phone administrator can use provisioning.xml to perform rudimentary file management on a phone, copying new files into the phone file system and deleting unwanted files from it. For example, you might use the File element to copy configuration files from a remote file server, or to update ringtones on the phone.
- Copy: (SourceName: <NetworkFilePath>; TargetName: <LocalFilePathName>). This copies a remote file (using the CopyFile function) to the specified place in the phone's file system.
- Delete: (Name: <LocalFilePathName>). This deletes a file from the phone's file system.
The following example shows how to specify attributes in the File element:
<category name="file">
<copy sourcename="source_file_name" targetname="target_file_name" />
<delete name="file_name" />
</category>
Phone-Services
The Phone-Services element allows you to implement check-sync notification.
- CheckSync: (0/1). If CheckSync is enabled, the phone responds to remote reboot requests via the check-sync notification. If the setting is 0 (or is not defined), the phone ignores them.
The following example shows how to specify attributes in the Phone-Services element:
<category name="phone-services">
<checksync enabled="1" />
</category>