Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/14/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 DMProcessConfigXMLfunction 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.

Copy Code 
// 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=\"http://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

Copy Code 
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.

Related Topics

See Also