Edit

Desktop COSA/APN database settings

  • Article

This topic describes the settings available in desktop COSA and the APN database (apndatabase.xml).

For more info about the Desktop COSA/APN database submission process, see Planning your desktop COSA/APN database submission.

For more info about COSA, see COSA overview.

For more info about the APN database, see APN database overview.

APN database-only settings

The following settings in the spreadsheet apply to the APN database only. These entries will be used if you are targeting Windows 8, Windows 8.1, or versions of Windows 10 before Windows 10, version 1703.

Setting name Description Optional or required Notes
CDMA ProviderID A 5-digit number that should match the CDMA provider ID (also called SID) reported by your device. Optional
CDMA ProviderName A string of no more than 36 characters that should match the CDMA provider name reported by your device. This setting is case sensitive. Optional
CertIssuerName The Cert Issuer Name of your signing certificate used for operator XML provisioning. Optional If specified, you must also specify the Cert Subject Name and Carrier GUID.
CertSubjectName The Cert Subject Name of your signing certificate used for operator XML provisioning. Optional If specified, you must also specify the Cert Issuer Name and Carrier GUID.
Carrier GUID The self-assigned GUID that is used in future operator XML provisioning packages. Optional If specified, you must also specify the Cert Subject Name and Cert Issuer Name.
GSM ProviderName A string of no more than 36 characters that should match the GSM provider name reported by your device. This setting is case sensitive. Optional This setting is only supported on Windows 8.1 and versions of Windows 10 before Windows 10, version 1703.
Purchase A yes or no value describing if the APN is provisioning or purchase. Required Possible values:
  • Y – if the APN is provisioning or purchase
  • N – if the APN is not provisioning or purchase

If Purchase Flag setting is Y, the Connect Flag setting must be N.
Connect A yes or no value describing if the APN is provisioning or purchase. Required Possible values:
  • Y – if the APN is provisioning or purchase
  • N – if the APN is not provisioning or purchase

If Connect Flag setting is Y, the Purchase Flag setting must be N.

APN database and desktop COSA settings

The following entries apply to both APN database and desktop COSA. For COSA, the minimum supported version of Windows required is indicated in the last column.

Setting name Description Optional or required Notes Minimum supported Windows version for COSA
UpdateType Describes whether the APN Database entry is new or modified. Required Possible values:
  • Add – A new entry
  • Change – Update an existing entry
  • Keep – Do not change the entry
  • Delete – Delete the entry
 Windows 10, version 1703
Country/Region The country or region for the APN entry. Required This entry might change to match how Windows refers to a particular country or region. Windows 10, version 1703
Operator The name of the operator. You do not need to include the country or region in this field. Required Ensure you use the same spelling and capitalization each time you submit an update for your APN entries. Windows 10, version 1703
MCC A 3-digit MCC value used for GSM IMSI submissions. Optional for ICCID ranges. Windows 10, version 1703
MNC A 2- or 3-digit MNC value used for GSM IMSI submissions. Optional for ICCID ranges. Windows 10, version 1703
IMSI Range - Start A 15-digit number that includes the MCC+MNC at the start of the number. Optional The number should end in 00.

If this setting and the IMSIRange - End setting is left blank but the MCC and MNC entries are specified, the entire MCC+MNC range is covered.

 Windows 10, version 1703
IMSI Range - End A 15-digit number that includes the MCC+MNC at the start of the number. Optional The number should end in 99.

If this setting and the IMSI Range - Start setting is left blank but the MCC and MNC entries are specified, the entire MCC+MNC range is covered.

 Windows 10, version 1703
ICCID Range - Start A 19- or 20-digit number that starts with 89 (the ICCID issuer identifier number). Optional The number should end in 00. Windows 10, version 1703
ICCID Range - End A 19- or 20-digit number that starts with 89 (the ICCID issuer identifier number). Optional The number should end in 99. Windows 10, version 1703
AccountExperienceURL Used by Windows Connection Manager if the user does not have an active plan and tries to connect to your network. Optional Helps improve the plan acquisition experience.

If both AppID and AccountExperienceURL are specified, AppID receives higher precedence and the UX will not display the AccountExperienceURL.

 Windows 10, version 1703
FriendlyName A name for this APN entry that is understandable and meaningful to subscribers. Optional Appears in the Windows Connection Manager in cases where Windows cannot automatically connect to the network. Windows 10, version 1703
AccessString For GSM networks, this is an APN such as data.contoso.com. For CDMA networks, this is an access string that includes a special dial code such as #777 or an Network Access Identifier such as example@contoso.com. Required Windows 10, version 1703
UserName The user name used to connect to your APN. This setting is case sensitive. Optional Windows 10, version 1703
Password The password used to connect to your APN. This setting is case sensitive. Optional Windows 10, version 1703
AuthProtocol Specifies the authentication protocol to be used for activating a Packet Data Protocol (PDP) context. Optional Possible values:
  • NONE – No authentication protocol is required
  • PAP – PAP authentication is required.
  • CHAP – CHAP authentication is required.
  • MsCHAPV2 –MSCHAPv2 is authentication is required.

This setting is only supported on Windows 8.1 and versions of Windows 10 before Windows 10, version 1703.

 Windows 10, version 1703
Compression Specifies if compression will be used at the data link for header and data transfer. Optional Possible values:
  • ENABLE – Compression is enabled
  • DISABLE – Compression is not enabled

This setting is only supported on Windows 8.1 and versions of Windows 10 before Windows 10, version 1703.

 Windows 10, version 1703
AutoConnectOrder Windows tries connections to the APNs provided by the operator and marked as "auto-connect" in APN database or COSA until it successfully connects to the mobile network. If all auto-connect attempts fail, Windows will show a prompt allowing the user to pick an APN or enter a custom APN. Optional If you have more than one access string for an operator, this setting must start with 1. This is needed for Windows to try several APN entries that share either an IMSI range, ICCID range, CDMA provider ID, or CDMA provider name when the user tries to connect. Windows 10, version 1809

Desktop COSA-only settings

The following settings apply to desktop COSA only. These entries will be used if you are targeting Windows 10, version 1703 and later.

Setting name Description Optional or required Notes Minimum supported Windows version
SupportDataMarketplace A true/false string describing whether a profile entry supports Mobile Plans. Optional

Before enabling this setting, please ensure that your Mobile Operator is part of the Mobile Plans program.

If left blank, defaults to "false."

 Windows 10, version 1703
SPN An identifier string for the Service Provider Name (SPN) Optional Helps to identify the MO/MVNO's network. If left blank, defaults to empty string and does nothing. Windows 10, version 1703
AlwaysOn Describes whether the connection is always on or not. Required If left blank, defaults to "true." Windows 10, version 1703
PurposeGroups A string specifying the purposes of the connection by a comma-separated list of GUIDs representing purpose values. Required The following purpose values are available:
  • Internet
  • MMS
  • IMS
  • SUPL
  • Purchase
  • Administrative
  • Application
  • eSIM provisioning

If left blank, defaults to "Internet."

 Windows 10, version 1703
Optional The following optional purpose group value is available:
  • LTE attach
Specifying an LTE attach APN through COSA is typically unnecessary because the attach info is usually managed directly by the underlying modem's hardware. However, in the case where the modem's hardware does not have an LTE attach APN value and the network is incapable of assigning one to the UE, the MO can optionally provide LTE attach information so that the UE can LTE attach without the user manually entering a value.		 Windows 10, version 1903
IPType A string specifying the network protocol of the connection. Optional Possible values:
  • IPv4
  • IPv6
  • IPv4v6

If left blank, defaults to "IPv4."

 Windows 10, version 1703
BrandingName The mobile broadband device typically provides the operator name, which Windows shows in the Windows Connection Manager. You can override this name by specifying a custom name in metadata. Optional If left blank, defaults to empty string and does nothing. Windows 10, version 1709
BrandingIcon A custom logo that appears in the Windows Connection Manager next to your network entry. Optional Icons must have transparent backgrounds and smooth edges. It's recommended to test the icon with both light and dark themes. They must also meet the following format and size requirements:
  • 256 x 256: 32-bit + Alpha
  • 48 x 48: 32-bit + Alpha
  • 48 x 48: 8-bit 256 color
  • 48 x 48: 4-bit 16 color
  • 32 x 32: 32-bit + Alpha
  • 32 x 32: 8-bit 256 color
  • 32 x 32: 4-bit 16 color
  • 24 x 24: 32-bit + Alpha
  • 24 x 24: 8-bit 256 color
  • 24 x 24: 4-bit 16 color
  • 16 x 16: 32-bit + Alpha
  • 16 x 16: 8-bit 256 color
  • 16 x 16: 4-bit 16 color
 Windows 10, version 1709
UseBrandingNameOnRoaming Determines if the branding should be displayed during roaming or not roaming. Optional Possible values:
  • 0 - Use only when connected to home network
  • 1 - Use when connected to home network and domestic roaming
  • 2 - Use when connected to home network, domestic roaming, and international roaming

If left blank, defaults to 0.

 Windows 10, version 1709
Roaming Specifies the roaming conditions under which the connection should be activated. Optional Possible values:
  • 0: Home network only
  • 1: All roaming conditions (home and roaming)
  • 2: Home and domestic roaming only
  • 3: Domestic roaming only
  • 4: Non-domestic roaming only
  • 5: Roaming only
If left blank, defaults to 1 (all roaming conditions).		 Windows 10, version 1709
DataMarketplaceRoamingUIEnabled This setting controls whether the roaming UI should be shown for a SIM or eSIM that is part of the Mobile Plans service. Optional This setting works with the SupportDataMarketPlace setting. The possible values are:
  • 0: The roaming indicator will never be displayed.
  • 1: The roaming indicator is displayed when the device is roaming in a foreign country.

If left blank, defaults to 1.

 Windows 10, version 1709
UIName If the target condition values (SPN, MCC, MNC, IMSI Range, ICCID Range, etc.) can't indicate the unique entry, then COSA will display this name to the end user to enable manual selection of which MO's connection value to use. Optional For example, ContosoMVNO is an MVNO. It doesn't have any unique values that can be used to distinguish itself from the main MO network, Contoso. In this case, UIName can be used and will be shown in the Windows Settings UI, enabling the user to manually select which MO provisioning settings to use. Windows 10, version 1709
UIOrder The index to control the UIName value's dropdown list picker position. Required if UIName is specified; Optional otherwise If not specified, defaults to 0. Windows 10, version 1709
ESIM_PROV A true/false string describing whether the profile is to be considered as an eSIM provisioning profile. Important Optional unless the MO supports an eSIM provisioning profile, in which case it is required.

If left blank, defaults to "false."

An eSIM provisioning profile is a single-purpose profile. When it is installed on the eUICC, it enables the user's equipment to establish a limited connection to the MO's walled garden in order to purchase a regular, operational eSIM profile.

 Windows 10, version 1709
AppID A string describing the Package Family Name (PFN) and application ID of a mobile operator's UWP companion app. Optional In Windows 10, version 1803 and later, AppID is used to identify MOs with their companion apps. AppID must be declared in this format:

PFN!AppId

Note This format is case sensitive.

To obtain the PFN and AppId for your app, follow these steps:

  1. Acquire the PFN as specified on View App Identity Details.
  2. Locate the AppId by opening your solution's AppManifest.XML file and querying the AppXManifest for the application ID.

For more info about UWP companion apps for MOs, see UWP mobile broadband apps.

 Windows 10, version 1803
Hotspot Determines if you want to permit users to share their mobile broadband connection as a personal hotspot. Optional Possible values:
  • Never
  • Always
  • EntitlementCheckRequired

If left blank, defaults to "Always."

The EntitlementCheckRequired option enables users to share their hotspots with an entitlement check, which requires a handler for Windows notification events. If this option is selected, you need to develop an MO UWP companion app to handle the entitlement check requests.

For more info about UWP companion apps for MOs, see UWP mobile broadband apps.

For more info about the EntitlementCheck API, see its UWP API reference page.

 Windows 10, version 1803
EnableAutoSlotSwitch Determines if you want to automatically switch slots when a SIM is inserted. Optional Possible values:
  • "false": When a new SIM is either inserted or removed, a toast is displayed asking if the user wants to switch slots. The slot is switched only if the user clicks "yes" on this toast.
  • "true": On SIM insert, the slot is switched automatically and then a toast is displayed informing the user that the slot has been switched. This toast doesn't take any button input from the user. The SIM removed behavior remains unchanged.

If not specified, defaults to "false".

 Windows 11
WifiProfiles Wifi profiles that will be included in the system while this mobile broadband profile is active. Optional

This entry supports multiple WifiProfile entries. Each WifiProfile entry must point to an .xml file with a WLANProfile. See WLANProfile Element.

See an example of WLAN Profile using EAP-AKA authentication.

 Windows 11