Share via

Programmatically Customizing a Device

  • Article

4/19/2010

You can change a device setting such as an alarm or the current networking status using the Configuration Service Provider (CSP) model to change, or "provision", the device.

To make such a change, you must first create an XML document that contains a description of the settings to be adjusted. Each change must include the CSP name, the attribute (also referred to as the "characteristic") and the value ("parm"). Multiple changes can be contained within one XML document.

Note   CPSs are controlled by a security model, and therefore the exact list of available features will vary on a per-device basis, as decided by device manufactures and mobile operators.

The XML provisioning document is then used by the Configuration Manager to make the changes. There are several ways in which the Configuration Manager can be invoked, including creating a CAB file, and using RAPI, but most developers will call the DMProcessConfigXML function directly, as this allows changes to be performed at run-time within an application.

In the following example, an XML document is constructed that will programmatically add a new web site to the Windows Mobile Explorer's list of favorites.

// WAP provisioning XML to add a new browser favorite.
LPCWSTR g_wszFavoriteXml =
  L"<wap-provisioningdoc>"
     L"<characteristic type=\"BrowserFavorite\">"
        L"<characteristic type=\"Baldwin Museum of Science\">"
           L"<parm name=\"URL\" value=\"https://www.baldwinmuseumofscience.com\"/>"
        L"</characteristic>"
     L"</characteristic>"
  L"</wap-provisioningdoc>";
// Use configuration XML to add a new browser favorite to the device.
HRESULT AddFavorite()
{
    HRESULT hr         = E_FAIL;
    LPWSTR wszOutput   = NULL;
    // Process the XML.
    hr = DMProcessConfigXML(g_wszFavoriteXml, CFGFLAG_PROCESS, &wszOutput);
    
    // The caller must delete the XML returned from DMProcessConfigXML.
    delete [] wszOutput;
    
    return hr;
}

This XML example is written using OMA Client Provisioning standard version 1.0, and should work on current Windows Mobile 6.5 devices (security model permitting). For information about the formatting of other versions, see OMA Client Provisioning Files.

When constructing the XML document, make sure that the parent node is set to the correct format (<wap-provisioningdoc> in this example), with the attribute and parameter contained inside

LPCWSTR g_wszFavoriteXml =
  L"<wap-provisioningdoc>"
     // Your provisioning XML goes here.
  L"</wap-provisioningdoc>";

The list of attributes that may be changed, and the associated XML, can be found in the section Configuration Service Provider Reference for Windows Mobile Devices.

To implement provisioning changes from managed code, you will need to create a wrapper for the native function DMProcessConfigXML. For more information, see Managed/Native Code Interoperability.

See Also

Concepts

Accessing low-level Device Information

Other Resources

Managing Windows Mobile Devices