Connectivity configuration

Article
03/26/2015

In Windows Phone 8.1, you can use runtime configuration to provision connectivity configurations for multiple scenarios, such as phones targeted to single operators, open market phones, and phones that need to distinguish between operators and plans. The previous method of provisioning connectivity settings, the OEM-created Automatic Data Configuration (ADC) DLL, is deprecated.

Before you start, review the following topics to learn about the new method of image customization for Windows Phone 8.1.

Runtime configuration covers the basics of runtime configuration and the supported connectivity configuration scenarios.
Customization answer file has an introduction and information about the answer file format and elements.
Managed Centralized Settings Framework (MCSF) describes the framework that is part of the customization and runtime configuration infrastructure.

Example: Creating a customization answer file

The basic steps to create a customization answer file with connectivity configuration are:

Enable runtime configuration and disable ADC. For more information, see Enabling runtime configuration.
Define Targets or conditions for when a variant can be applied, such as keying off of a SIM’s MCC, MNC, and SPN.
Define settings for a Variant, which are applied if the associated target's conditions are met. For more about the priority of variant selection keys, see Variant selection during runtime.

Important

The desired order of priority for cellular data and MMS connection settings is the following:

User-configured settings
Pushed provisioning through OMA Client Provisioning
Connectivity settings configured through runtime configuration

However, Connection Manager tries connections in alphabetical order based on connection name. Due to this logic, connections configured through runtime configuration should be prepended with “zzz” to ensure that these connections are used as a lowest priority. The logic of alphabetical ordering of connections is subject to change in the future.

A sample OEM customization answer file can be found in the %WPDKCONTENTROOT%\Samples\Customization directory. This answer file shows several configured customizations and it imports two answer files that contain real connection settings data for AT&T and T-Mobile.

The following sample customization answer file shows a basic example of connectivity configuration for two different mobile operators on a dual SIM phone. For details about specific configuration, see the following topics:

Important

All APN, proxy, and policy entries referring to the same connection must be defined within the same <Settings> element in the answer file.

Important

For dual SIM phones, connection settings must be unique for each SIM. To ensure unique settings, OEMs can use the $(__MVID) macro as part of all connection names.

    <?xml version="1.0" encoding="utf-8" ?>  
    <!--  Copyright (c) Microsoft Corporation.  All rights reserved.  -->  

    <ImageCustomizations xmlns="https://schemas.microsoft.com/embedded/2004/10/ImageUpdate"  
                         Name="Sample Customization File"  
                         Description="Sample customization XML."  
                         Owner="Microsoft"  
                         OwnerType="OEM">  

    <Targets>
        <Target Id="FabrikamMO">
            <TargetState>
                <Condition Name="MCC" Value="310" />
                <Condition Name="MNC" Value="001" />
                <Condition Name="SPN" Value="Fabrikam Inc." />
            </TargetState>
        </Target>
        <Target Id="ContosoMO">
            <TargetState>
                <Condition Name="MCC" Value="310" />
                <Condition Name="MNC" Value="101" />
            </TargetState>
            <TargetState>
                <Condition Name="MCC" Value="310" />
                <Condition Name="MNC" Value="102" />
            </TargetState>
            <TargetState>
                <Condition Name="MCC" Value="310" />
                <Condition Name="MNC" Value="103" />
            </TargetState>
        </Target>
    </Targets>

    <Static>
        <Settings Path="Multivariant">
            <Setting Name="Enable" Value="1" />
            <Setting Name="BrandingSlot" Value="0" />
        </Settings>
        <Settings Path="AutoDataConfig">
            <Setting Name="Enable" Value="0" />
        </Settings>
    </Static>

    <Variant Name="Contoso Settings">
        <TargetRefs>
            <TargetRef Id="ContosoMO" />
        </TargetRefs>

        <Settings Path="Connections">

            <!-- internet APN -->
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/AccessPointName" Value="contoso_internet_apn" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/UseRequiresMappingsPolicy" Value="0" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/AlwaysOn" Value="1" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/ConnectionType" Value="gprs" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/AuthType" Value="None" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/IPType" Value="IPv4" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/ExemptFromDisablePolicy" Value="1" />
            <Setting Name="Cellular/zzzcontoso_internet $(__MVID)/OemConnectionId" Value="12345678-1234-1234-1234-123456789012" />

            <!-- MMS APN -->
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/AccessPointName" Value="contoso_mms_apn" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/UseRequiresMappingsPolicy" Value="1" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/AlwaysOn" Value="0" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/ExemptFromDisablePolicy" Value="1" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/ConnectionType" Value="gprs" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/AuthType" Value="None" />
            <Setting Name="Cellular/zzzcontoso_mms $(__MVID)/OemConnectionId" Value="12345678-1234-1234-1234-123456789012" />

            <!-- MMS proxy -->
            <Setting Name="Proxies/contoso_mms_proxy $(__MVID)/Server" Value="proxy.contoso.com" />
            <Setting Name="Proxies/contoso_mms_proxy $(__MVID)/Port" Value="80" />
            <Setting Name="Proxies/contoso_mms_proxy $(__MVID)/ConnectionName" Value="zzzcontoso_mms $(__MVID)" />
            <Setting Name="Proxies/contoso_mms_proxy $(__MVID)/Type" Value="HTTP" />
        </Settings>

        <!-- Push proxy gateway -->
        <Settings Path="PGList/1234-PRXY $(__MVID)/1234-PRXY-PHY $(__MVID)">
            <Setting Name="TRUST" Value="1" />
            <Setting Name="AddressType" Value="E164" />
            <Setting Name="Address" Value="1234" />
            <Setting Name="PushEnabled" Value="1" />
            <Setting Name="MatchedNapID" Value="1234-NAPDEF $(__MVID)" />
        </Settings>

        <!-- MMS proxy configuration -->
        <Settings Path="PGList/contoso_mms-PRXY $(__MVID)/contoso_mms-PRXY-PHY $(__MVID)">
            <Setting Name="AddressType" Value="IPV4" />
            <Setting Name="Address" Value="proxy.contoso.com" />
            <Setting Name="MatchedNapID" Value="zzzcontoso_mms $(__MVID)" />
        </Settings>

        <!--  MMS application configuration  -->
        <Settings Path="Messaging/PerSimSettings/$(__ICCID)/w4">
            <Setting Name="APPID" Value="w4" />
            <Setting Name="NAME" Value="contoso_mms $(__MVID)" />
            <Setting Name="ADDR" Value="https://mmsc.contoso.com" />
            <Setting Name="TONAPID" Value="zzzcontoso_mms $(__MVID)" />
            <Setting Name="TOPROXY" Value="contoso_mms-PRXY $(__MVID)" />
            <Setting Name="MS" Value="1024" />
        </Settings>

        <!-- Security policy -->
        <Settings Path="DeviceManagement/Policies/OMACP">
            <Setting Name="NetwpinRoles" Value="SECROLE_KNOWN_PPG" />
            <Setting Name="UserpinRoles" Value="SECROLE_KNOWN_PPG" />
            <Setting Name="UsernetwpinRoles" Value="SECROLE_KNOWN_PPG" />
        </Settings>
    </Variant>

    <Variant Name="Fabrikam Settings">
        <TargetRefs>
            <TargetRef Id="FabrikamMO" />
        </TargetRefs>
        
        <Settings Path="Connections">
            <!-- internet APN -->
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/AccessPointName" Value="FabrikamApn" />
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/UseRequiresMappingsPolicy" Value="0" />
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/AlwaysOn" Value="1" />
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/ConnectionType" Value="gprs" />
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/AuthType" Value="None" />
            <Setting Name="Cellular/zzzFabrikam $(__MVID)/IPType" Value="IPv4v6" />

            <!-- MMS APN -->
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/AccessPointName" Value="FabrikamApn" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/UseRequiresMappingsPolicy" Value="1" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/AlwaysOn" Value="0" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/ConnectionType" Value="gprs" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/AuthType" Value="None" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/ExemptFromDisablePolicy" Value="1" />
            <Setting Name="Cellular/zzzFabrikam_mms $(__MVID)/IPType" Value="IPv4v6" />

        <!-- Push proxy gateway -->
        <Settings Path="PGList/123-PRXY $(__MVID)/123-PRXY-PHY $(__MVID)">
            <Setting Name="TRUST" Value="1" />
            <Setting Name="AddressType" Value="E164" />
            <Setting Name="Address" Value="123" />
            <Setting Name="PushEnabled" Value="1" />
            <Setting Name="MatchedNapID" Value="123-NAPDEF $(__MVID)" />
        </Settings>

        <!-- MMS application configuration -->
        <Settings Path="Messaging/PerSimSettings/$(__ICCID)/w4">
            <Setting Name="APPID" Value="w4" />
            <Setting Name="NAME" Value="zzzFabrikam $(__MVID)" />
            <Setting Name="ADDR" Value="https:/mms.fabrikam.com" />
            <Setting Name="TONAPID" Value="zzzFabrikam $(__MVID)" />
        </Settings>

        <!-- Security policy -->
        <Settings Path="DeviceManagement/Policies/OMACP">
            <Setting Name="NetwpinRoles" Value="SECROLE_KNOWN_PPG" />
            <Setting Name="UserpinRoles" Value="SECROLE_KNOWN_PPG" />
            <Setting Name="UsernetwpinRoles" Value="SECROLE_KNOWN_PPG" />
        </Settings>
        <Settings Path="DeviceManagement/Policies/MMS">
            <Setting Name="MMSMessageRoles" Value="SECROLE_ANY_PUSH_SOURCE" />
        </Settings>
    </Variant>
</ImageCustomizations>

Adding additional custom conditions

In some cases, MCC, MNC, and SPN values may not be enough to differentiate between mobile operators, such as between a mobile operator and an MNVO. If you need to distinguish mobile operators based on additional properties such as GID1 or IMSI range, you must extend the set of condition providers. OEMs can use other code that is running on the phone to create a key that the runtime configuration engine can use to further differentiate between the mobile operator and the MVNO.

For information about how to extend the runtime configuration engine for this purpose, see Define extension provisioning keys.

Using the Roaming key for roaming state changes

A Roaming key with values of either 0 (non-roaming) or 1 (roaming) is supported as a condition in the customization answer file. This key allows OEMs to create configuration sets, or variants, in the customization answer file that are triggered when the roaming state changes.

For additional information and requirements for this key, see the Roaming key section in Runtime configuration. The following sample shows how to use the Roaming key.

<?xml version="1.0" encoding="utf-8" ?>
<!--  Copyright (c) Microsoft Corporation.  All rights reserved.  -->
<ImageCustomizations xmlns="https://schemas.microsoft.com/embedded/2004/10/ImageUpdate"
                     Name="Sample Customization File"
                     Description="Sample customization XML."
                     Owner="Microsoft"
                     OwnerType="OEM">

  <Targets>
    <Target Id="Fabrikam_Variant1">
      <TargetState>
        <Condition Name="MCC" Value="310" />
        <Condition Name="MNC" Value="001" />
        <!-- UIName and UIOrder must be the same for all targets for the same variant. -->
        <Condition Name="UIName" Value="Fabrikam" />
        <Condition Name="UIOrder" Value="1" />
      </TargetState>
    </Target>
    
    <Target Id="Fabrikam_NonRoaming_Variant1">
      <TargetState>
        <Condition Name="MCC" Value="310" />
        <Condition Name="MNC" Value="001" />
        <Condition Name="Roaming" Value="0" />
        <!-- UIName and UIOrder must be the same for all targets for the same variant. -->
        <Condition Name="UIName" Value="Fabrikam" />
        <Condition Name="UIOrder" Value="1" />
      </TargetState>
    </Target>
    
    <Target Id="Fabrikam_Roaming_Variant1">
      <TargetState>
        <Condition Name="MCC" Value="310" />
        <Condition Name="MNC" Value="001" />
        <Condition Name="Roaming" Value="1" />
        <!-- UIName and UIOrder must be the same for all targets for the same variant. -->
        <Condition Name="UIName" Value="Fabrikam" />
        <Condition Name="UIOrder" Value="1" />
      </TargetState>
    </Target>
  </Targets>

  <Variant Name="Fabrikam non-roaming settings for Variant 1">
    <TargetRefs>
      <TargetRef Id="Fabrikam_NonRoaming_Variant1" />
    </TargetRefs>
    <!-- All Fabrikam settings that are required when non-roaming for Variant 1. -->
  </Variant>

  <Variant Name="Fabrikam roaming settings for Variant 1">
    <TargetRefs>
      <TargetRef Id="Fabrikam_Roaming_Variant1" />
    </TargetRefs>
    <!-- All Fabrikam settings that are required when roaming for Variant 1. -->    
  </Variant>
  
  <Variant Name="Fabrikam settings for Variant 1">
    <TargetRefs>
      <TargetRef Id="Fabrikam_Variant1" />
    </TargetRefs>
    <!-- All Fabrikam settings that don't require customization per roaming state for Variant 1. -->    
  </Variant>
  
</ImageCustomizations>

Specifying settings through a UI

If on-device keying is not sufficient to determine the correct mobile operator settings, users can specify the correct settings through a UI. The UI shows up during initial phone setup and during SIM changes.

For more information, see the Selecting the correct settings through a UI section in Variant selection during runtime.

Dual SIM

For dual SIM devices, runtime configuration will configure each SIM’s settings automatically based on the targets and variants that you create.

Connection settings must be unique for each SIM. To ensure unique settings, OEMs can use the $(__MVID) macro as part of all connection names.

For SIM-based settings, you can use the $(__IMSI) and $(__ICCID) macros that are built-in to MCSF. When these types of settings are being provisioned, the macros are replaced with the IMSI or ICCID string for the current SIM card.

For an example of this, see the Example section in this topic, or in the Multi-settings section of the Managed Centralized Settings Framework (MCSF) topic.

CountryTable.xml

The runtime configuration engine uses a CountryTable XML data store to track the following information:

2-digit versus 3-digit MNCs
Mapping of GeoID to MCC values, which are used for provisioning locale or country-based settings during initial phone setup when the phone has no SIM.

This XML data store is currently stored in a Microsoft package, but OEMs ultimately need to maintain this file to update or add more values and to reflect any geopolitical changes. To see the data contained in this file, see the CountryTable\CountryTable.xml file provided in the WPBlue_Customizations_Code_Samples.zip. This package is available for download on the Connect Web site. OEMs can override the default country lookup table and instruct the runtime configuration engine to use an OEM-provided mapping table instead. For more information on how to do this, see Override the default CountryTable.xml.

The following example shows part of the data contained in the CountryTable.xml file:

<countrytable>
    <country mcc="202" iso3166="GR" GeoID="98"/><!-- Greece -->
    <country mcc="297" iso3166="ME" GeoID="270"/><!-- Montenegro (Republic of) -->
    <!-- snipped... -->
    <country mcc="302" iso3166="CA" GeoID="39"><!-- Canada -->
        <mnclist>
            <mnc id="220"/>
            <mnc id="221"/>
            <mnc id="222"/>
            <mnc id="250"/>
            <mnc id="270"/>
            <mnc id="290"/>
            <!-- snipped... -->
    </country>
    <!-- snipped... -->
</countrytable>

The following example shows a scenario where a Target is specified with only a Condition that contains an MCC value:

  <Targets>
    <Target Id="USACarriers310">
      <TargetState>
        <Condition Name="MCC" Value="310" />
      </TargetState>
    </Target>
    <Target Id="USACarriers311">
      <TargetState>
        <Condition Name="MCC" Value="311" />
      </TargetState>
    </Target>
  </Targets>

In this example, variants that refer to the USACarriers* Target will be provisioned when the phone is booted with SIMs that have MCC=310 or MCC=311 in their IMSI. However, variants associated with the USACarriers310 Target will be provisioned if the user boots without a SIM and selects United States as their country or locale during initial phone setup. Variants referring to USACarriers311 will not be provisioned.

In the no-SIM during initial phone setup case, the runtime configuration engine maps the GeoID from the CountryTable.xml to the lowest MCC value for that GeoID in the CountryTable. So, for example, if 310 is the lowest MCC for the United States, you need to make sure the Targets for non-SIM variants contain MCC=310 and not 311.

Provisioning with runtime configuration

APN configuration

Proxy configuration

Connection policy configuration

MMS configuration

Push proxy gateway configuration

Send comments about this topic to Microsoft

Connectivity configuration

Example: Creating a customization answer file

Adding additional custom conditions

Using the Roaming key for roaming state changes

Specifying settings through a UI

Dual SIM

CountryTable.xml

Related topics

Additional resources