DMProcessConfigXML

Send Feedback

This function grants local and remote access to the configuration management functionality of the mobile device. This function enables the submission of Extensible Markup Language (XML) information to change the settings of a mobile device.

Syntax

HRESULT DMProcessConfigXML(
  LPCWSTR pszWXMLin, 
  DWORD dwFlags, 
  LPWSTR* ppszwXMLout
);

Parameters

  • pszWXMLin
    [in] The input XML buffer containing the configuration data.

  • dwFlags
    [in] Specifies an action flag. The following table shows the possible values.

    Option Value Description
    CFGFLAG_PROCESS 0x0001 The configuration management service and the Configuration Service Providers process the input data.
    CFGFLAG_METADATA 0x0002 The configuration management service gathers and returns metadata for any XML parameter elements it encounters.
  • ppszwXMLout
    [out] Pointer to the output XML buffer. For more information, see Remarks.

Return Values

Returns the standard HRESULT value S_OK to indicate success. The following table shows the additional error codes that may be returned.

Value Description
CONFIG_E_OBJECTBUSY Another instance of the configuration management service is currently running.
CONFIG_E_CANCELTIMEOUT Waiting for the session to be timed out.
CONFIG_E_ENTRYNOTFOUND No metabase entry was found.
CONFIG_E_CSPEXCEPTION An exception occured in one of the Configuration Service Providers.
CONFIG_E_TRANSACTIONINGFAILURE A configuration management service failed to roll back properly. The affected settings might be in an unknown state.
CONFIG_E_BAD_XML The XML input is invalid or malformed.

Remarks

In Windows Mobile 5.0 and later, you can call DMProcessConfigXML from within the setup DLL file of a .cab file.

The caller of DMProcessConfigXML is responsible for cleanup of the output buffer that the ppszwXMLout parameter references. Memory is allocated in the implementation by means of the new [] operator. Thus the caller must use the delete [] <varname> statement to free the output buffer.

Note   If DMProcessConfigXML retrieves a document, the caller should parse the document for errors.

The Configuration Manager component is transactional and must process only one configuration request at a time to prevent collisions. Therefore, the DMProcessConfigXML function processes only one XML configuration request at a time.

Code Example

The following code example demonstrates how to use DMProcessConfigXML.

Note   To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

// WAP provisioning XML to add a new browser favorite.
LPCWSTR g_wszFavoriteXml = 
    L"<wap-provisioningdoc> "
    L"   <characteristic type=\"BrowserFavorite\"> "
    L"      <characteristic type=\"MSN Search\"> "
    L"         <parm name=\"URL\" value=\"https://search.msn.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;

}

Requirements

Pocket PC: Pocket PC 2003 and later.
Smartphone: Smartphone 2002 and later.
OS Versions: Windows CE 3.0 and later.
Header: Cfgmgrapi.h.
Library: Aygshell.lib.

See Also

Device Configuration API | Configuration Service Providers | Managing Devices | Provisioning for Windows Mobile-Based Devices

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.