Device provisioning with XML

Article
01/18/2005

I guess this post is loosely related to deployment – I’ve been working on another customer question today around pre-configuring a VPN connection to use IPSec pre-shared keys. One of the really useful features of Smartphone that made it to Pocket PC 2003 is the Configuration Manager feature. This lets you configure pretty much any aspect of your device using simple wap-provisioning XML through the Configuration Manager on the device. There are several well defined areas such as pocket IE favourites, dial-up networks, WiFi networks, VPN, GPRS, proxies and so on. In addition to the well defined configuration settings, you can also just go ahead and party all over the registry. On the device, Configuration Manager examines the XML and uses registered Configuration Service Providers (CSPs) modules to do the dirty work of changing settings. The list of CSP’s is, of course, extensible.

So what does this xml look like? This is the piece I built for creating the VPN entry:

<wap-provisioningdoc>

</characteristic>

</wap-provisioningdoc>

Let me take you through it briefly (the docs are pretty reasonable around this feature so go look it up in Pocket PC SDK docs for more detail):

The first characteristic defines the time of CSP used – in this case VPN configuration.

Next is the name of this entry, so when you look in setting on the device you will see this name on the VPN tab.

VPN connections in general provide a bridge from one network type to another e.g. Internet to Work. SrcId and DestId are GUID’s that refer to a list of network types held in the device (again extensible) and denote what networks this VNP bridges between. In this case SrcId refers to the pre-defined Internet value and DestId refers to the pre-defined Work value.

Then there is the Phone setting denoting the entry point URL, user name, domain and password which are all pretty self explanatory.

Type denotes if the VPN connection uses PPTP (value 0) or IPSec (value 1).

IPSecAuth denotes either cert based authentication (0) or pre-shared key authentication (1).

PresharedKey denotes the value of the key. My customer question was how long the key can be: the docs indicate 256 ASCII chars and the screen dialog is limited to that size as well. For practicality I guess this key could accept a base64 encoded key of about 170 bytes.

Enabled indicates that this setting is available.

Once you have your XML file how do you throw it at Configuration Manager? Fortunately there are lots of ways:

Check out the RapiConfig tool that comes with Pocket PC 2003 SDK (and the Smartphone SDK as well). Standard install puts it here: \program files\windows ce tools\WCE420\Pocket PC 2003 SDK\Tools. Attach a device via USB / Serial and setup and ActiveSync connection. Run RapiConfig /P <myxml.xml> and it will apply the settings. Quite a useful tip when writing your XML, try running a query against the device first to see what settings are there already – it’s a great way to get started. Queries are formed with <characteristic-query> or <parm-query> xml for example:

<wap-provisioningdoc>

<characteristic-query type="CM_VPNEntries"/>

</wap-provisioningdoc>

And running them is exactly the same. This example gives a full list of VPN settings.

All that RapiConfig is doing it to call a system API remotely and extract the results to the desktop. The DMProcessConfig api can be used directly buy your code in the device but there is one small gotcha! If you want to call this api from managed code, be aware the API allocates the return buffer using the C++ “new” function so your code is in sever danger of leaking unless you can call the C++ delete operator (or the ‘free’ runtime function as delete defers to free in its implementation). Here is a sample (see left bar for disclaimer for this code):

using System;

using System.IO;

using System.Runtime.InteropServices;

using System.Windows.Forms;

using System.Text;

namespace XMLConfig

{

/// <summary>

/// Summary description for DMProcessConfig.

/// </summary>

public class DMProcessConfig

{

[DllImport("aygshell.dll")]

private static extern int DMProcessConfigXML(string pszWXMLin, int dwFlags, IntPtr ppszwXMLout);

[DllImport("coredll.dll")]

private static extern void free(int buffer);

public DMProcessConfig()

{

}

unsafe static public bool ProcessXML(string Filename)

{

StreamReader sr = new StreamReader(Filename, Encoding.ASCII);

string XML = sr.ReadToEnd();

fixed (int * OutPtr = new int[1])

{

IntPtr outptr = (IntPtr)OutPtr;

try

{

int result = DMProcessConfigXML(XML, 1,outptr);

if (result !=0)

{

MessageBox.Show("Failed");

}

else

{

free(*OutPtr);

}

catch(Exception e)

{

MessageBox.Show(e.Message);

}

return true;

}

There are a couple more ways to get XML running on the device. The first is over the air (OTA) provisioning but I haven’t done anything with OTA so let’s leave that for a bit. The second is through the new “.cpf” file. A CPF file is simply a CAB file that contains just one file _setup.xml. The CPF extension is associated with WCELoad.EXE (just like a standard CAB file), when a CPF file is opened the xml is extracted and thrown at Configuration Manager. The whole operation is silent except for a notification mail that appears in the user’s inbox indicating success or failure.

Building a CPF is pretty straight forward:

1> Take your xml file and rename it to _setup.xml

2> Go into the Pocket PC tools directory as above

3> Type MakeCab.exe /D COMPRESS=OFF _setup.xml myOutCpf.

The COMPRESS=OFF is needed for Pocket PC because WCELoad doesn’t support compressed cab’s (yet!). Next copy your CPF to a device nearby and click on it in explorer. Hey presto, XML is applied.

There are some things not quite perfect about configuration manager with probably the most annoying being lack of WiFi WEP key provisioning, but it is a great feature that I use lots for application deployment.

Marcus

Comments

Anonymous
February 03, 2005
Hi, good articole! I'd like know more about OTA, have you got some example? thanks Giuseppe
Anonymous
February 11, 2005
Very nice write up of the Device provisioning!
I got it working on my first trial!! :)

I am struggling with the OTA part my self now...any chance of you making an OTA add on on this excellent article??
I am finding my self having trouble finding an easy way to send my compiled wbxml file out to my smartphone.....
Do you have any tips?
/kent
Anonymous
April 21, 2005
CPF files are not associated with Wceload but with wceloadsp.exe.

Ced
Anonymous
May 02, 2005
Hi,
very nice article, but are a couple of weeks that I'm don't find anything about ota provisioning on pocket pc with windows mobile :-(
I mean I have found many docs, also from msdn library but no complete example (xml->wbxml) that work fine. for example have anybody tried to configure email via OTA for a pocket pc?

best regards
Lisa
Anonymous
May 04, 2006
I would like to distribute cpf files from a web server. what mime type do I have to use so pocket IE could associate them with wceloadsp.exe and install them silently ?

Thank You
Anonymous
September 28, 2006
Nice article! I would like to configure a gprs connection. Where can I find information about the XML file format that I must use?

Best Regards,

Carlos
Anonymous
October 18, 2006
>Looking for GPRS provisioning info... I copied this from my unit's cingular provisioning file: <characteristic type="CM_GPRSEntries"> <characteristic type="Cingular GPRS"> <parm name="DestId" value="{888C8CE5-E23F-4350-B0FB-34D4FAA7A8C6}" /> <parm name="Enabled" value="1" /> <parm name="UserName" value="ISP@CINGULARGPRS.COM" /> <parm name="Password" value="CINGULAR1" /> <parm name="Domain" value="" /> <parm name="SpecificIpAddr" value="0" /> <parm name="IpAddr" value="" /> <parm name="SpecificNameServers" value="0" /> <parm name="DnsAddr" value="" /> <parm name="AltDnsAddr" value="" /> <parm name="WinsAddr" value="" /> <parm name="AltWinsAddr" value="" /> <parm name="IpHeaderCompression" value="1" /> <characteristic type="DevSpecificCellular"> <parm name="BearerInfoValid" value="1" /> <parm name="GPRSInfoValid" value="1" /> <parm name="GPRSInfoProtocolType" value="2" /> <parm name="GPRSInfoL2ProtocolType" value="PPP" /> <parm name="GPRSInfoAccessPointName" value="isp.cingular" /> <parm name="GPRSInfoAddress" value="" /> <parm name="GPRSInfoDataCompression" value="1" /> <parm name="GPRSInfoHeaderCompression" value="1" /> <parm name="GPRSInfoParameters" value="" /> </characteristic> </characteristic>
Anonymous
November 23, 2006
Hi, I have WAP gprs setting to configure on windows mobile 5.0 for browsing thru' Internet explorer of WM 5.0. Below is my wap setting to use. Basically, I want these settings to be used when user connects to internet. WAP browser settings ================= WAP G/w IP : 10.10.1.50 Port : 9201 APN : myWAPAPN Username: WAPuname Password: WAPpwd I went thru' MSDN docs and found that I have to break the above settings into 2 portions. CM_GPRSEntries for specifying APN and CM_ProxyEntries to set the wap g/w, port etc. Following are my configuration for CM_GPRSEntries and CM_ProxyEntries. <characteristic type="CM_GPRSEntries"> <characteristic type="my-GPRS"> <parm name="DestId" value="{436EF144-B4FB-4863-A041-8F905A62C572}"/> <characteristic type="DevSpecificCellular"> <parm name="BearerInfoValid" value="1"/> <parm name="GPRSInfoValid" value="1"/> <parm name="GPRSInfoProtocolType" value="2"/> <parm name="GPRSInfoL2ProtocolType" value="PPP"/> <parm name="GPRSInfoAccessPointName" value="myWAPAPN"/> <parm name="GPRSInfoAddress" value=""/> <parm name="GPRSInfoDataCompression" value="1"/> <parm name="GPRSInfoHeaderCompression" value="1"/> <parm name="GPRSInfoParameters" value=""/> </characteristic> </characteristic> </characteristic> <characteristic type="CM_ProxyEntries"> <characteristic type="MyWapBrowser"> <parm name="SrcId" value="{436ef144-b4fb-4863-a041-8f905a62c572}" /> <parm name="DestId" value="{7022e968-5a97-4051-bc1c-c578e2fba5d9}" /> <parm name="Proxy" value="10.10.1.50:9201" /> <parm name="Extrainfo" value="10.10.1.50:9201" /> --> dont know what it is for <parm name="Type" value="2" /> <parm name="Username" value="WAPuname" /> <parm name="Password" value="WAPpwd" /> </characteristic> </characteristic> Please let me know if this is the correct way to do it. I went thru MSDN docs, but could not get a clarity regarding "SrcId" and "DestId". i want to know what exactly these GUIDs for internet and wap n/w are? and why they are used. It would be great if you can explain the above setting clearly. If any change to be made to set these settings, please let me know. hoping to get a quick response... Thanks in advance...
Anonymous
November 23, 2006
For clarification, let me give info on the GUID's above "{436EF144-B4FB-4863-A041-8F905A62C572}" - Default internet network on device. "{7022e968-5a97-4051-bc1c-c578e2fba5d9}" - Default WAP network on device. thanks
Anonymous
February 18, 2007
Hi, Can you please let me know how the existing connections can be modified by editing the XML files. My email id is yuvraj2011@gmail.com I require some help urgently, Regards Yuvraj
Anonymous
February 26, 2007
I really need a way of telling my PPC to send all webservice requests for "www.SyncServer.com" through the work network. The PPC's using my app will only have network access at the depot where the employees work and will not have a SIM card installed. I'll give this a try tomorrow when I start work but unfortunately I have no way of knowing whether or not I have succeeded until Friday when I can get to a depot and give it a try, so any tips etc before then would be very gratefully received! Thanks Pete
Anonymous
March 12, 2007
Once you create the .xml file you can package it up into a .cpf file that work like a cab file. http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mobilesdk5/html/wce51howcreatingcpffile.asp
Anonymous
March 29, 2007
Very good blog- but I've one question to the XML Provisioning using the Registry Conf. Service Provider. There the parm-Tag comes along with the datatype attribute. And that's where I don't know how to enter/handle binary data. Below is my example: <wap-provisioningdoc> <characteristic type="Registry"> <characteristic type="HKCU\ControlPanel\Owner"> <parm name="Owner" value=" -don't know what to insert here...?- " datatype="binary" /> </characteristic> </characteristic> </wap-provisioningdoc> Thx in advance for help! My Mailaddress is mathias.knoll-AT-salomon.at
Anonymous
April 05, 2007
Mathias. The binary data has to be Base64 encoded. for example the binary data "ABCDEF etc" becomes the value "QUJDREVGIGV0Yw==". There are a couple of places where this isn't exactly true but it works correctly for the Owner blob in HKCUControlPanelOwner. It will not be exactly correct if you try to modify the Notes value using the same mechanism as there appears to be an inconsistency in the CSP's handling of that field between PPC2003 and WM56. To populate the Owner data in this way you will have to build the data structure and then encode the resulting binary blob.
Anonymous
August 13, 2007
I really wanna know much about OTA. Would u mind to give me some example?? Thanks, Hendry
Anonymous
August 25, 2008
I require XML dump to push gprs setting on my handset HTC Touch,can anyone help me..its quite urgent. My email id is :-neha.bagla@cellebrum.com
Anonymous
September 02, 2008
did anyone here has configured smartphone/ppc "menu structure" and "settings window" (reordering of icons) through provisioning xml.
Anonymous
October 05, 2008
Thanks! Nice article... Prabhu
Anonymous
December 01, 2008
The comment has been removed
Anonymous
July 15, 2009
Hi, I am working for a pocket PC Application.I am trying to rename a folder inside My Documents using "FileOperation" CSP. Is it possible to do like this or is there any method available to rename a folder using "FileOperation" CSP. Regards, Kathir
Anonymous
July 15, 2009
Kathir there is no rename characteristic so you need to copy the file then delete the original. Marcus

Partager via

Device provisioning with XML

Comments

Ressources supplémentaires