Table of contents
TOC
Collapse the table of content
Expand the table of content

DMProcessConfigXMLFiltered function

Last Updated: 10/28/2016

Important
The use of this function for automatic data configuration (ADC) is deprecated in Windows Phone 8.1. Please see Connectivity configuration for more information about the new process for provisioning connectivity configuration. However, this function is still supported for other OEM uses.

Configures phone settings by using OMA Client Provisioning XML. Use of this function is strictly limited to the following scenarios.

  • Adding dynamic credentials for OMA Client Provisioning.

  • Manufacturing test applications. These applications and the supporting drivers must be removed from the phones before they are sold.

Microsoft recommends that this function is not used to configure the following types of settings.

  • Security settings that are configured by using CertificateStore, SecurityPolicy, and RemoteWipe, unless they are related to OMA DM or OMA Client Provisioning security policies.

  • Non-cellular data connection settings (such as Hotspot settings).

  • File system files and registry settings, unless they are used for OMA DM account management, mobile operator data connection settings, or manufacturing tests.

  • Email settings.

Note The DMProcessConfigXMLFiltered function has full functionality in Windows 10 Mobile and Windows Phone 8.1, but it has a read-only functionality in Windows 10 desktop.

Syntax

HRESULT STDAPICALLTYPE DMProcessConfigXMLFiltered(
         LPCWSTR pszXmlIn,
   const WCHAR   **rgszAllowedCspNode,
   const DWORD   dwNumAllowedCspNodes,
         BSTR    *pbstrXmlOut
);

Parameters

pszXmlIn

  • [in] The null–terminated input XML buffer containing the configuration data. The parameter holds the XML that will be used to configure the phone. DMProcessConfigXMLFiltered accepts only OMA Client Provisioning XML (also known as WAP provisioning). It does not accept OMA DM SyncML XML (also known as SyncML).

rgszAllowedCspNode

  • [in] Array of WCHAR\* that specify which configuration service provider nodes are allowed to be invoked.

dwNumAllowedCspNodes

  • [in] Number of elements passed in rgszAllowedCspNode.

pbstrXmlOut

  • [out] The resulting null–terminated XML from configuration. The caller of DMProcessConfigXMLFiltered is responsible for cleanup of the output buffer that the pbstrXmlOut parameter references. Use SysFreeString to free the memory.

If DMProcessConfigXMLFiltered retrieves a document, the pbstrXmlOut holds the XML output (in string form) of the provisioning operations. If DMProcessConfigXMLFiltered returns a failure, the XML output often contains "error nodes" that indicate which elements of the original XML failed. If the input document does not contain queries and is successfully processed, the output document should resemble the input document. In some error cases, no output is returned.

Return value

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

Return codeDescription

CONFIG_E_OBJECTBUSY

Another instance of the configuration management service is currently running.

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 service provider 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

The processing of the XML is transactional; either the entire document gets processed successfully or none of the settings are processed. Therefore, the DMProcessConfigXMLFiltered function processes only one XML configuration request at a time.

The usage of DMProcessConfigXMLFiltered depends on the configuration service providers that are used. For example, if the input .provxml contains the following two settings:

<wap-provisioningdoc>
    <characteristic type="NAPDEF">
        <characteristic type="Internet" mwid="1">
            <parm name="NAME" value="Contoso Internet APN"/>
            <parm name="BEARER" value="GSM-GPRS"/>
            <parm name="NAP-ADDRESS" value="wap.contoso"/>
            <parm name="NAP-ADDRTYPE" value="APN"/>
            <parm name="INTERNET" value="1"/>
        </characteristic>
    </characteristic>
    <characteristic type="BrowserFavorite">
        <characteristic type="Contoso">
            <parm name="URL" value="http://www.contoso.com"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Then, the second parameter in the call to DMProcessConfigXMLFiltered would have to have the following definition.

LPCWSTR rgszAllowedCspNodes[] =
{
    L"NAPDEF",
    L"BrowserFavorite"
};

This array of configuration service provider names indicates which .provxml contents should be present. If the provxml contains "EMAIL2" provisioning but rgszAllowedCspNodes does not contain EMAIL2, then DMProcessConfigXMLFiltered fails with an E_ACCESSDENIED error code.

The following code sample shows how this array would be passed in. Note that szProvxmlContent does not show the full XML contents for brevity. In actual usage, the "…" would contain the full XML string shown above.

WCHAR szProvxmlContent[] = L"<wap-provisioningdoc>...</wap-provisioningdoc>"; 
BSTR bstr = NULL;

HRESULT hr = DMProcessConfigXMLFiltered(
                szProvxmlContent,
                rgszAllowedCspNodes,
                _countof(rgszAllowedCspNodes),
                &bstr
                );

/* check error */

if ( bstr != NULL )
{
    SysFreeString( bstr );
    bstr = NULL;
}

Requirements

Minimum supported client

None supported

Minimum supported server

None supported

Minimum supported phone

Windows Phone 8.1

Header

Dmprocessxmlfiltered.h

Library

Dmprocessxmlfiltered.lib

DLL

Dmprocessxmlfiltered.dll

See also

SysFreeString

© 2017 Microsoft