다음을 통해 공유


DMProcessConfigXML (Windows Embedded CE) (Windows Embedded CE 6.0)

1/6/2010

This Device Configuration API function grants local access to the configuration-management functionality of a Windows Embedded CE powered device. Application developers can use this to configure device settings. This function enables the submission of Open Mobile Alliance (OMA) Client Provisioning Extensible Markup Language (XML) information to change the settings of a device.

Syntax

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

Parameters

  • pszWXMLin
    [in] The input XML buffer containing the configuration data. The parameter holds the XML that will be used to configure the device.
  • 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 from the configuration XML file. Changes are applied.

    CFGFLAG_METADATA

    0x0002

    The configuration-management service gathers and returns metadata for any XML parameter elements it encounters. No changes are processed.

  • ppszwXMLout
    [out] Pointer to the output XML buffer. For more information, see Remarks.

Return Value

Returns the standard HRESULT value S_OK to indicate success. The following table shows the additional error codes that might 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 occurred 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

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. Therefore, 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.

Note

DMProcessConfigXML accepts only Open Mobile Alliance (OMA) Client Provisioning XML. It does not accept OMA Device Management (DM) SyncML XML. OMA Device Management (DM) SyncML XML is not supported by Windows Embedded CE 6.0.

Code Example

The following code example demonstrates how to use DMProcessConfigXML.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

// 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;
}

Requirements

Header cfgmgrapi.h
Library aygshell.lib

See Also

Concepts

Configuring Device Connection Settings by using OMA XML

Other Resources

Connection Manager OMA XML Provisioning File
Connection Manager Configuration