XML Provisioning

Introduction

Generally, provisioning represents the process of configuring device settings before and after deployment to end users. Provisioning a Windows Mobile-based device involves creating a provisioning XML document that contains configuration information, and then sending the file to the device. There are 2 standards for provisioning and the XML document must conform to one of them:

• Open Mobile Alliance (OMA) Device Management (DM)
• OMA Client Provisioning - the Wireless Application Protocol (WAP) based provisioning standard

In what follows, we shall only be concerned with OMA Client Provisioning XML documents, because this is the format used for the XML setup file ("_setup.xml") within Windows Mobile/CE CABinets.

Not all devices support XML provisioning. All SmartPhone devices as well as Pocket PC devices starting from Windows Mobile 5 support XML provisioning through several delivery mechanisms (CAB packages, CPF packages - CAB Provisioning Format files or RAPI - Remote Application Programming Interface while connected to a PC). Pocket PC 2003 (and 2003 Second Edition) as well as older devices do not have support for XML provisioning through any of the mentioned delivery options.

OMA Client Provisioning XML files

The general format of a provisioning document conforming to this standard is showed in the following example:

<wap-provisioningdoc>
  <characteristic type="Root-level CSP1">
    <characteristic type="1st-level Characteristic">
      <parm name="ParmName" value="ParmValue"/>
    </characteristic>
  </characteristic>
  <characteristic type="Root-level CSP2">
    <characteristic type="Another 1st-level Characteristic">
      <parm name="Another_ParmName" value="Another_ParmValue"/>
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

The first entry under the top-level <wap-provisioningdoc> element is a <characteristic> element that references a specific Configuration Service Provider (CSP). Configuration Service Providers execute configuration requests by changing or querying the values of settings. One provisioning XML file typically contains configuration information for multiple CSPs.

Beneath this root level CSP characteristic element, any number of child <characteristic> elements can be used to perform or limit the scope of an operation. For example, the FileOperation CSP has characteristics that perform operations (such as copy and delete), and others that specify directories (such as type="\Windows"). Beneath the last <characteristic> element there can be any number of <parm> elements.

OMA Client Provisioning XML documents are based on the MSPROV DTD Format. The elements defined by this DTD are explained in the following article: MSPROV DTD Elements.

XML Client Provisioning examples

It exists a multitude of Configuration Service Providers which can be used to configure various device settings, such as email, networking, phone and security settings. See the Configuration Service Provider Reference for more details.

<wap-provisioningdoc>
  <characteristic type="BrowserFavorite">
    <characteristic type="Example link">
      <parm name="URL" value="http://www.example.com" />
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

<wap-provisioningdoc>
  <characteristic type="BrowserFavorite">
    <nocharacteristic type="Example link" />
  </characteristic>
</wap-provisioningdoc>

<wap-provisioningdoc>
  <characteristic type="Registry">

    <!-- Create/modify REG_SZ and REG_DWORD values under the following key -->
    <characteristic type="HKCU\Software\Test Key">
      <parm name="StringValue" value="String value data" datatype="string" />
      <parm name="DWORD_Value" value="1234" datatype="integer" />
    </characteristic>

    <!-- Delete a registry value under the following key -->
    <characteristic type="HKCU\Software\Second Test Key">
      <noparm name="Value To Delete" />
    </characteristic>

    <!-- Delete a registry key, with all its values and subkeys -->
    <nocharacteristic type="HKLM\Software\RegKey To Delete" />

  </characteristic>
</wap-provisioningdoc>

<wap-provisioningdoc>
  <characteristic type="FileOperation">

    <!-- Create a new directory under '\Program Files' (%CE1%) and create a shortcut
         to '\Windows\solitare.exe' in this new folder -->
    <characteristic type="%CE1%\New Folder" translation="install">
      <characteristic type="MakeDir" />
      <characteristic type="Shortcut to Solitare.lnk" translation="install">
        <characteristic type="Shortcut">
          <parm name="Source" value="%CE2%\solitare.exe" translation="install"/>
        </characteristic>
      </characteristic>
    </characteristic>

    <!-- Move the shortcut created above under '\Windows\StartUp' (%CE4%) such that the
         game is launched after a soft reset -->
    <characteristic type="%CE4%" translation="install">
      <characteristic type="MakeDir" />
      <characteristic type="Copy of Shortcut to Solitare.lnk" translation="install">
        <characteristic type="Move">
          <parm name="Source" value="%CE1%\New Folder\Shortcut to Solitare.lnk" translation="install"/>
        </characteristic>
      </characteristic>
    </characteristic>

    <!-- Delete the '\Program Files\New Folder' directory created initially -->
    <characteristic type="%CE1%\New Folder" translation="install">
      <characteristic type="RemoveDir" />
    </characteristic>

  </characteristic>
</wap-provisioningdoc>