Configuring Devices through XML Provisioning from the Desktop

  • Article

Many developers know (or should know) the bedrock principle of software development: "KNOW THY USER, FOR HE IS NOT THEE" [cit. from David S. Platt, President of Rolling Thunder Computing]. So if you know that device users are not as geek as you and it might even be that they won't be completely confident about copying a CAB and launch it from within the File Explorer on the device, then you may consider the following scenario. Imagine you want to let a Windows Mobile-based device user configure a device without asking him\her to copy a CAB to the device, but instead you want to leverage on the ActiveSync's or WMDC's "Add/Remove Programs" semi-automatic feature: so, we're talking about a sort of a desktop ConfigureMyDevice.exe (or .bat, or .cmd), which internally launches CeAppMgr.exe (still on the desktop), which the user can simply double-click on, and the next time he\she cradles the device it's automatically deployed and installed.

Well, when a developer asked for support about that, I didn't know the post provided the Windows Mobile Dev Team Injecting Provisioning XML into a cab using VS 2005, and we came out with a slightly different approach, yet satisfying in our case and still based on the /postxml option provided by CabWiz.exe. The limitation of the VS2005 and VS2008 in this case is that Smart Device CAB projects allow developer to target only the FileOperation and the Registry CSPs (Configuration Service Provider).

You may say at this point that if your goal is to "simply" configure a cradled device connected through ActiveSync\WMDC you can also programmatically launch RapiConfig.exe instead of relying on ActiveSync\WMDC's "Add/Remove Programs" (in any case, note that using "Add/Remove Programs" does NOT require a partnership with the cradled device, so you wouldn't ask so to device users), but remember that RAPI may be disallowed or restricted on the target device (more on this possibly on a later post) and then there might be some issues with redistributing RapiConfig.exe as it is. If I recall correctly, developers are not allowed to redistribute RapiConfig.exe and if you really need to let users have it and don't want to ask them to download\install one of the Windows Mobile SDKs, you can let them download the much smaller Microsoft Exchange Server ActiveSync Certificate-Based Authentication Tool (123 KB), which contains an edition of RapiConfig.exe as well.

The steps  that were satisfactory in our case were:

0. Create a Smart Device CAB project through VS2005

1. Through the File Editor add it a dummy txt file, whose contents are for example (but really, it can be anything):
==============================================================================
THIS IS SAMPLE CODE AND IS ENTIRELY UNSUPPORTED. THIS CODE AND INFORMATION
IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO AN IMPLIED WARRANTY OF MERCHANTABILITY AND/OR
FITNESS FOR A PARTICULAR PURPOSE.
==============================================================================
This will show how the FileOperation CSP will be added the resulting _setup.xml file. Adding a "dummy" file was a required step, because otherwise Visual Studio complains stating that "You tried to build a setup project but did not include any files. You must specify at least one file before continuing. ".

2. Through the Registry Editor, add a key: this will show how the Registry CSP will be added the resulting _setup.xml file. Contrarily to the file, this is not strictly required.

3. You can't add other CSPs by using VS2005's editors within the Smart Device CAB project: if you want to add other XML you have to launch CabWiz.exe manually, and using /postxml command-line option. See below.

4. Starting from the INF file created in the steps above, copy the SmartDeviceCab1.INF file in a folder (let’s name the folder C:\test and the file test.inf). You should edit the .INF file in 2 points:
- AppName="SmartDeviceCab1" (you may want to change the name that will appear on the device “smartdevicecab1 was installed successfully…”)
- Under [SourceDisksNames], modify to the current directory, i.e.
1=,"Common1",,"C:\test"

5. Create a XML file with the provisioning you want to be added to the _setup.xml: please note that you must NOT add <wap-provisioningdoc>. For example, the usual test one:

 <characteristic type="BrowserFavorite"> 
  <characteristic type="Southridge Video Store"> 
    <parm name="URL" value="<https://www.southridgevideo.com/>"/> 
    <parm name="Order" value="0"/> 
  </characteristic> 
</characteristic>

and name it _setupToAppend.xml.

6. now you should launch CabWiz.exe, and in order to make things reproducible you save it in a .bat or .cmd: < "C:\Program Files\Microsoft Visual Studio 8\SmartDevices\SDK\SDKTools\CabWiz.exe" "C:\test\test.inf" /postxml _setupToAppend.xml /nouninstall >

(NOTE the /postxml option)

This will create the CAB file: you should open it to verify if the resulting contained _setup.xml is what you were looking for and if it contains the 2 .000 and .001 files based on the "dummy" txt file.

7. Now that we have the CAB, you should use the sample2.INI file - in my case I used the following (you might want to change the cab file name):

[CEAppManager]

Version = 1.0

Component = test

[test]

Description = Sample2

CabFiles = test.CAB

8. Finally, you should cradle the device (or you can do it later) and launch the CeAppMgr.exe by specifying the .ini: < "C:\Program Files\Microsoft ActiveSync\CEAPPMGR.EXE" "C:\test\sample2.ini" > (you don't need to create an .exe, but a .bat or a .cmd would suffice).