Professional Documents
Culture Documents
Retele Wi Fi Telef
Retele Wi Fi Telef
Mobile broadband
Overview
Overview of mobile broadband
Mobile broadband WinRT API overview
Overview of mobile broadband Windows Runtime APIs
Overview of mobile broadband Windows Runtime APIs
Connection Profile API
Device Services Extension API
Provisioning API
SIM PIN API
SMS API
Subscriber and Device Information API
USSD API
Common tasks for mobile broadband Windows Runtime APIs
Create a MobileBroadbandAccount object
Create a MobileBroadbandDeviceInformation object
Create a MobileBroadbandNetwork object
Determine if a device is PIN-locked
Determine which mobile broadband network is currently connected
Determine which Windows device is being used to connect to the network
Discover whether the network device radio is turned on
Enumerate available mobile broadband accounts
Establish temporary network connectivity
Get information about the currently registered network
Get the IMEI, ICCID, IMSI and telephone numbers for the mobile broadband
device
Know when network connectivity changes
Open the networks list
Receive notification for device information account changes
Receive notification when mobile broadband accounts are added or removed
Retrieve ConnectionProfile objects for a MobileBroadbandAccount
Unlock a device
Best practices for using Mobile Broadband Windows Runtime API
Best practices for handling account arrival and removal events
Best practices for connecting to the mobile broadband network
Mobile operator hardware overview
Using metadata to configure mobile broadband experiences
Overview of using metadata to configure mobile broadband experiences
Account provisioning
COSA/APN database
Introduction to COSA/APN database
APN schema definition
APN elements
APN elements overview
OperatorList
Operator
HardwareIdList (APN element)
HardwareId (APN element)
ConnectionInfoList
ConnectionInfo
TrustedCertificateList
TrustedCertificate (APN element)
APN example
COSA overview
APN database overview
COSA/APN database submission
Planning your desktop COSA/APN database submission
Desktop COSA/APN database settings
Testing your desktop COSA/APN database submission
Submitting the desktop COSA/APN database update
Service metadata
Service metadata overview
Delivering experiences for MVNOs
Developer guide for creating service metadata
Service identifier ownership updates
Service metadata package schema reference
MobileBroadbandInfo XML schema
MobileBroadbandInfo XML schema overview
MobileBroadbandInfo XML schema definition
MobileBroadbandInfo XML elements
MobileBroadbandInfo XML elements list
MobileBroadbandInfo
NetworkConfiguration
MobileBroadbandProfiles
Purchase
Internet
AllowStandardUserPinUnlock
AllowTethering
ProvisioningEngine element
ProvisioningEngine
TrustedCertificates
TrustedCertificate (MobileBroadbandInfo)
SubjectName
IssuerName
MobileBroadbandInfo XML example
PackageInfo XML schema
PackageInfo XML schema overview
PackageInfo XML schema definition
PackageInfo XML elements
PackageInfo XML elements list
PackageInfo
MetadataKey
ModelIDList
ModelID
HardwareIdList (PackageInfo)
HardwareId (PackageInfo)
Locale
LastModifiedDate
MultipleLocale
PackageStructure
Metadata
Relationships
ExperienceID
LanguageNeutralIdentifier
MetadataBuilderInformation
Application
Version
PackageInfo XML data types
GUIDType
PackageInfo XML Example
ServiceInfo XML schema
ServiceInfo XML schema overview
ServiceInfo XML Schema Definition
ServiceInfo XML elements
ServiceInfo XML elements list
ServiceInfo
ServiceCategoryList
ServiceCategory
ServiceName
ServiceDescription1
ServiceDescription2
ServiceNumber
ServiceProvider
ServiceIconFile
ServiceSpecificExtension
ServiceInfo XML Data Types
GUIDType
ServiceInfo XML Example
SoftwareInfo XML schema
SoftwareInfo XML schema overview
SoftwareInfo XML Schema Definition
SoftwareInfo XML elements
SoftwareInfo XML elements list
SoftwareInfo
DeviceCompanionApplications
Package (SoftwareInfo)
Identity (SoftwareInfo)
Applications
Application
DeviceNotificationHandlers
DeviceNotificationHandler
PrivilegedApplications
Package (SoftwareInfo - priviliged applications)
Identity (SoftwareInfo - priviliged applications)
SoftwareInfo XML Example
WindowsInfo XML schema
WindowsInfo XML schema overview
WindowsInfo XML Schema Definition
WindowsInfo XML elements
WindowsInfo XML elements list
WindowsInfo
ShowDeviceInDisconnectedState
LaunchDeviceStageOnDeviceConnect
LaunchDeviceStageFromExplorer
LaunchApplicationOnDeviceConnect
AutoplayHandler
PackageIdentity
Application
Verb
AutoplayType
EnableAutoPlayForRegisteredApps
DesktopAutoplayHandler
WindowsInfo XML Example
Using mbidgenerator.exe to generate hardware IDs
Mobile operator scenarios
Mobile Plans
Mobile Plans description
Mobile Plans overview
Mobile Plans sytem architecture
Mobile Plans scenarios
Mobile Plans features
Mobile Plans catalog
Mobile operator gateway page
Mobile operator web portal
Callback notifications
eSIM download error handling
Account management
Walled garden
Toast notifications
Mobile Plans onboarding
Onboarding overview
Development
Integration
Launch
Appendix
General appendix
Legacy callback notifications
eSIM management on Windows for mobile operators and OEMs
Creating and configuring Internet Sharing experiences
Developing apps using multiple PDP contexts
Developing SMS apps
Introduction to developing SMS apps
SMS device storage limits
Enumerate SMS devices
Get SMS device information
Read received SMS by using the text-mode interface
Run new SMS received background events
Send SMS by using custom character sets
Send SMS by using the text-mode interface
Calculate characters and segments of a draft SMS
Specify mobile telephone numbers
Windows automatically segments long messages
Windows automatically selects optimal character encoding
Set SMS declarations
Enabling mobile broadband experiences using portable hotspot devices
Introduction to enabling mobile broadband experiences using portable hotspot
devices
Communication channels
Personal hotspot communication channels
Network cost information element
PnP-X for mobile broadband apps
Enabling mobile operator notifications and system events
Introduction to enabling mobile operator notifications and system events
Develop an app to handle the MobileOperatorNotification event
Mobile operator notification event technical details
Mobile operator notification scenarios
Integrating Windows with wireless hotspots
Introduction to integrating Windows with wireless hotspots
Get started with a hotspot authentication app
Review the hotspot authentication sample
Update the hotspot authentication sample
Verify background events
Hotspot authentication methods
Captive portals
WISPr authentication
WISPr authentication overview
Provisioning for hotspot authentication
Handling large numbers of SSIDs
Handling the hotspot authentication event
Hotspot 2.0
Provisioning Windows using a website
Understanding and configuring Windows Connection Manager
UWP mobile broadband apps
UWP mobile broadband apps overview
Mobile broadband app scenarios
Account management
App startup
Help and support
Hot spot authentication
Live tile updates
Notifications
Plan purchase
Premium services
Designing the user experience of a mobile broadband app
Introduction to designing the user experience of a mobile broadband app
Design the landing page of a mobile broadband app
Design branding in a mobile broadband app
Design account balance and usage info in a mobile broadband app
Design messages in a mobile broadband app
Design billing pages in a mobile broadband app
Design purchase flows in a mobile broadband app
Design help and support pages in a mobile broadband app
Design services and goods pages in a mobile broadband app
Integrate a mobile broadband app with other Windows components
Mobile broadband
4/13/2022 • 2 minutes to read • Edit Online
Use the docs in this section to learn more about mobile broadband and how to configure mobile broadband
experiences for your customers.
Overview
Using metadata to configure mobile broadband experiences
Mobile operator scenarios
Overview of mobile broadband
4/13/2022 • 29 minutes to read • Edit Online
Windows 8, Windows 8.1, and Windows 10 simplify mobile broadband connectivity for users, while offering
new opportunities for mobile network operators. Users enjoy a streamlined, consistent connection flow.
Windows 8, Windows 8.1, and Windows 10 reduce your need to develop traditional connection management
apps so development resources can be focused on customer interaction, including account management and
value-added services.
Windows 8, Windows 8.1, and Windows 10 present an opportunity to reimagine and streamline the existing
mobile broadband ecosystem.
Earlier versions of mobile broadband hardware required custom Windows drivers. With the current
Mobile Broadband class driver, certified mobile broadband devices have a consistent experience without
the need to install custom drivers. This streamlining presents an opportunity to provide customers with a
“just works” experience while possibly reducing support overhead.
Customized connection management experiences duplicate Windows functionality and have different UX
models than the rest of Windows. These connection managers have to be deployed and maintained by
the operator and their ISV partners.
The need for a custom driver and for custom connection management software meant that USB-based
mobile broadband devices need to also perform a USB storage function in order to deliver that custom
software to the user’s PC. This dual-mode device concept often requires the user to switch between
storage mode and modem mode, adding an extra task before the user can successfully connect to the
network.
Highlight unique services and capabilities that make your customer experience unique. Windows 8,
Windows 8.1, and Windows 10 provide the opportunity to focus on the customer connection and to
highlight your unique value-add through a UWP mobile broadband app, previously known as a mobile
operator app.
Key scenarios
This section describes key scenarios that are part of the current mobile broadband experience that you can
choose to enable. Consider each of these scenarios in the context of your business models when you plan which
Windows components your app must interact with.
Plan purchase
Connecting an active device
Operator notifications and system events
Providing accurate usage and plan data
Internet sharing
Wi-Fi hotspot authentication
Displaying account information to the user
Enabling other devices and app scenarios
Plan Purchase
A seamless plan purchase experience makes it easier for users to buy connectivity and enables the operator to
accept new customers without the need for support or retail-store intervention. There are two purchase plan
options:
The mobile broadband app and service metadata is already installed on the PC. This could happen for
PCs that have embedded mobile broadband hardware where the OEM has preloaded the mobile
broadband app and service metadata on the Windows image or an alternate Internet connection is
available.
The mobile broadband app and service metadata is not installed on the PC. This could happen when you
plug in a hardware dongle and an alternate Internet connection is not available.
Regardless of the plan purchase option, there are various sub states based on the state of the SIM or CDMA
mobile broadband device. Cold SIMs (no associated plan), warm SIMs (ready to accept a plan), and hot SIMs
(already active with a plan) will likely present a different experience based on how you want to structure the
purchase flow.
Mobile broadband app is already installed or an alternate Internet connection is available
In this case, an embedded device, mobile broadband app, and service metadata is probably already installed on
the PC with a SIM before the user attempts to activate service. Another possibility is that the user does not yet
have the mobile broadband app but has an alternate Internet connection to download the app. The following
steps occur automatically when the SIM is inserted:
1. The mobile broadband service reads the International Mobile Subscriber Identity (IMSI), the Integrated
Circuit Card ID (ICCID) for GSM networks, the provider ID (SID) for CDMA networks, or the provider name
for CDMA networks and generates a set of Hardware IDs (HWIDs).
Note This step is only necessary if the OEM has not inserted the SIM and preloaded the mobile
broadband app and service metadata.
2. When the PC is connected to the Internet, the HWIDs are sent to Windows Metadata and Internet Services
(WMIS). WMIS identifies the operator and returns the appropriate service metadata package.
Note This step is only necessary if the OEM has not inserted the SIM and preloaded the mobile
broadband app and service metadata.
3. Windows uses the service metadata to identify and retrieve the mobile broadband app from the
Microsoft Store. The app is installed automatically. In Windows 8.1 and Windows 10, the app is not
pinned to the Start screen.
Note This step is only necessary if the OEM has not inserted the SIM and preloaded the mobile
broadband app and service metadata.
4. Your operator logo and name appear in the Networks list in Windows Connection Manager. The user can
connect to your network.
5. Windows Connection Manager tries to connect by using the network profile configuration information in
the service metadata. The next step depends on the result of the connection:
If the initial connection is successful and Internet connectivity is available, nothing further happens.
The user has previously purchased service and has an active account.
If the initial connection is successful but Internet connectivity is not available, the mobile
broadband app starts and the user is asked to for a purchase plan.
If the initial connection fails and the error code indicates that network service has not yet been
purchased, the mobile broadband app started. The app can determine the appropriate response.
For example, if the error code is due to lack of connectivity, the app may need to direct the user to
complete the purchase by telephone or by connecting to an alternate Internet connection.
If the initial connection fails with another error code, Windows connection manager notifies the
user about the error. The mobile broadband app is not started.
6. When the mobile broadband app opens, you should ensure that the app is written to make a secure
connection to the backend billing infrastructure so that the user can purchase a subscription. This process
is proprietary for each operator and Microsoft is not involved in the purchase process. The app
establishes this connection through a limited mobile broadband connection (that the operator network
needs to enable) or over an alternate Internet connection, such as Wi-Fi.
7. When plan purchase is complete, the mobile broadband app generates a metadata provisioning file that
is passed to the provisioning agent. This configures Windows with information about the plan that the
user has purchased.
Impor tant The steps above also apply to an external device that is attached to the PC with an alternate
Internet connection.
Mobile broadband app is not installed and no alternate Internet connection is available
An external mobile broadband device, such as a hardware dongle, can be inserted into PCs that may not have an
alternate Internet connection available and may not have a mobile broadband app installed. The following steps
describe how a plan purchase experience can be built to work around limitations in this scenario:
1. As soon as the mobile broadband hardware is detected, the Windows Mobile Broadband service reads
the IMSI, the ICCID, the provider ID, or the provider name and generates a set of HWIDs that represent the
each value read from the device. The Windows Mobile Broadband service listens for mobile broadband-
related events.
2. When the user clicks Connect , the HWID values are used to locate the connection settings in the
Windows APN database as follows:
If the initial connection is successful and Internet connectivity is available, nothing further happens.
The user has previously purchased service and has an active account.
If the initial connection is successful but Internet connectivity is not available, the user is taken to
the URL specified in the APN database for this HWID range.
If the initial connection fails, Windows Connection Manager notifies the user about the error. Your
website should assist the user in purchasing a plan.
3. After the user completes the plan purchase, the website generates a metadata provisioning file and
passes it to the provisioning agent. This configures Windows with basic information about the plan that
the user has purchased. Depending on the network structure, one of the following occurs:
The user is granted Internet access on the current connection.
The provisioning file includes instructions to disconnect and reconnect to the same network or a
different network, which will provide Internet access.
At this point, the user is online. Now that an Internet connection is available, Windows detects the mobile
broadband hardware and downloads and installs the service metadata and the mobile broadband app.
4. The HWIDs that are calculated from the SIM or mobile broadband device are sent to WMIS. WMIS
identifies the operator and returns the appropriate service metadata package.
5. Windows uses the service metadata to identify and retrieve the associated mobile broadband app from
the Microsoft Store. The app is installed automatically and registered for background events. In
Windows 8.1 and Windows 10, the app is not automatically pinned to the Start screen. Registering for
background events allows the app to do things such as reacting to local data usage counters, receiving
operator SMS messages, connecting to Wi-Fi hotspots, and handling entitlement checks.
6. When a background event occurs, the app generates a more complete provisioning file, if needed, and
passes it to the provisioning agent. This configures Windows with information about the plan that the
user has purchased.
Connecting an Active Device
When a device with an active mobile broadband plan is attached to a PC, the experience is similar to that for
purchase, except that the attempted connection leads to the Internet. Windows will not start the mobile
broadband app for mobile broadband or connect to the mobile operator’s website. Instead, the app is installed
in the background.
1. When the mobile broadband hardware is detected, the Mobile Broadband service reads the IMSI, the
ICCID, the provider ID, or the provider name and generates HWIDs.
2. When the user clicks Connect , the HWID values are used to locate appropriate connection settings within
the Windows APN database. For an active device, the connection is successful and Internet connectivity is
available.
3. At this point, the user is online. Now that an Internet connection is available, Windows will detect the
mobile broadband hardware and download and install the service metadata and the mobile broadband
app.
Windows 8.1 and Windows 10 can connect to an operator network during Windows Setup if a mobile
broadband device with an active plan is attached to the PC. The mobile broadband network appears in the
Networks list during Windows Setup along with Wi-Fi networks. Similar to the process for connecting an active
device, a HWID is generated based on the detected mobile broadband hardware and is used to locate
appropriate connections settings within the Windows APN database.
Operator Notifications and System Events
In order to keep users informed about their account status, the mobile broadband app needs to perform some
activities even when the user is not interacting with it. These activities include responding to operator SMS or
network-initiated USSD messages, notifying the user that they are approaching their data limit, notifying the
user that their data plan has expired, and notifying the user of their roaming status. Incoming SMS messages are
available to privileged apps that have been granted access to the SMS capabilities on the PC by the service
metadata package.
Some SMS messages come directly from the mobile network operator and should be displayed to the user by
using the mobile broadband app. The mobile broadband app can invoke a toast notification when it receives an
operator SMS message.
For operator messages that are not intended to be seen by the end-user, the mobile broadband app can process
these and act appropriately. The Windows Notification Service provides the most efficient direct-to-app
notification channel, but Windows also supports the use of incoming SMS and Unstructured Supplementary
Service Data (USSD) notifications from the mobile broadband network.
More information about handling SMS messages can be found in Developing SMS apps. More info about
operator notifications can be found in Enabling mobile operator notifications and system events.
1. The service metadata declares that the mobile broadband app wants to access operator notifications. A
private background event is created and the app is registered for operator notification events at the time
that it is installed.
2. When the app applies provisioning metadata, it includes a description of all SMS and USSD messages
that should be considered operator messages.
Upon receipt of an SMS or USSD message, the Mobile Broadband service compares the message to the
description provided in the provisioning metadata. If parsing rules have been included, the Mobile Broadband
service also interprets the message and updates the information about data usage.
If the message is a match, the System Event Broker is notified to invoke the private background event for that
mobile broadband app. If not, the System Event Broker is notified to invoke the public SMS event.
Some examples of what the operator could include in the mobile broadband app for responses to incoming
SMS messages include the following:
Immediately syncing current data usage
Displaying a notification to the user
Updating the app’s live tile
Retrieving and applying updated provisioning metadata
Note Windows 8, Windows 8.1, and Windows 10 do not include an SMS app with the operating system so a
mobile broadband app or a third-party SMS app to which the operator gives privileged access is needed in
order to display SMS messages to the user.
Note Building a mobile broadband app with SMS support is necessary to show notification UI to the end user
when text messages are received, which may be required to conform to regulatory requirements or best
practices in certain markets.
SMS functionality is available to mobile broadband apps, UWP apps that are given privileged access to mobile
network operators, UWP apps that are given privileged access by the PC OEM (if the mobile broadband device is
embedded in the PC), or the mobile broadband device IHV (if the mobile broadband device is removable).
Mobile network operators and the PC OEM (or the mobile broadband device IHV) specify privileged apps
through service metadata. For more information about service metadata, see Using metadata to configure
mobile broadband experiences.
Providing accurate usage and plan data
Windows provides Data Usage and Subscription Manager APIs that the mobile broadband app can use to
describe the user’s data plan. The mobile broadband app can update this API with information about the data
plan size, metered vs. non-metered plan, and an updated data usage value from the operator’s network.
Windows will check the data usage information that has been set for the user by using these APIs and change
the behavior of core features. For example, Windows Update will only auto-download critical updates when the
user is using a metered network. Usage information is also accessible to third-party apps via the Data Usage
and Subscription Manager APIs.
The following is a walkthrough of the various features that the mobile broadband app can choose to utilize in
order to keep the user informed of their data usage.
1. Local data counters estimate that usage on the profile has changed by more than 5 percent of the user’s
data limit since the last update from the operator. This 5 percent increment is hard-coded and the mobile
broadband app can make use of background events to wake itself up and react to each 5 percent
increment.
2. Data Usage and Subscription Manager is a Windows component that does this 5 percent usage
increment tracking. It notifies the System Event Broker to trigger a background event for each 5 percent
increment in the local estimated usage.
3. The System Event Broker invokes the mobile broadband app to handle the background event. (Other
triggers, such as an incoming notification, might cause this to occur.) The mobile broadband app can
choose what to do when it is invoked for this purpose.
4. A best practice is for the app to handle this event by retrieving the most current usage information from
the operator’s billing infrastructure to validate how much usage the user has actually gone through. This
is likely an asynchronous operation over the network and the mobile broadband app needs to be able to
react to delays in getting this information from the operator’s billing infrastructure. If there is a significant
delay in the data usage tracking, the mobile broadband app can query the local data counters to fill the
gap between the current time and the most recent data.
5. When the web query to the operator’s billing infrastructure completes, the mobile broadband app can
apply updated provisioning metadata that describes the most up-to-date usage information available
back to Windows.
6. The app publishes the updated information through the Data Usage and Subscription Manager APIs.
7. Windows components and third-party apps on the PC can access this usage information by using the
Windows.Networking.Connectivity.ConnectionProfile class. Apps can adjust their behavior
accordingly. For example, the app can use a lower quality video stream on metered networks.
Internet sharing
Mobile broadband provides users with connectivity wherever they go. However, not every device has a mobile
broadband device. Windows 8.1 and Windows 10 enable users to share their mobile broadband connectivity
over Wi-Fi with friends and family using different devices.
Customers can turn on Internet Sharing in PC settings. They can also change the SSID, the password for the Wi-
Fi network, and see how many people are sharing the connection.
For customers that want to use the Mobile Broadband connectivity on another one of their devices, Windows
makes it even easier. Simply open Networks list on a WiFi-capable PC running Windows 8.1 or Windows 10,
click the SSID of the sharing device, and then click Connect . Windows will handle all the device configuration
and inter-device communication.
The following is a walkthrough of the various features that you can configure and manage how Internet Sharing
works on Windows 8.1 and Windows 10.
1. You can choose whether or not your customers are able to use Internet Sharing by uploading a service
metadata package that is automatically downloaded and installed on the PC.
2. Using service metadata, you can also select whether the mobile broadband app runs an entitlement
check against the service to see if a specific customer has purchased a data plan that supports tethering.
3. The mobile broadband app registers for a background event to run the entitlement check whenever the
user enables Internet Sharing and instructs Windows on whether or not to allow it.
4. As part of the provisioning metadata, you can specify which PDP context and APN to use for the shared
data traffic, as well as the maximum number of devices that can share the connection at one time.
5. Using the updated local data usage APIs, you can create an experience in your mobile broadband app to
show customers how much data has been used by other devices that shared their mobile broadband
connection.
For more information about Internet Sharing, see Creating and configuring Internet Sharing experiences.
Wi-Fi hotspot authentication
As part of the provisioning metadata, the mobile broadband app can describe the hotspots that a user can
authenticate using their operator-supplied credentials. These may include WISPr 1.0 hotspots or encrypted
hotspots using EAP-SIM, EAP-AKA, or other supported EAP methods.
Windows will then automatically offload data traffic onto these hotspots when in range. You may want to do this
in order to offload network traffic from your cellular data networks to land-line-based Wi-Fi locations. In some
cases, the Wi-Fi hotspot may have increased speeds or better coverage than the cellular data network for that
location.
You can also make a hotspot less preferred than the mobile network, making it available for Windows to use
when the mobile broadband connection is not available but not used for data offload.
Setup
The mobile broadband app generates a provisioning file that contains the SSIDs and authentication
mechanism for WiFi hotspots that user can authenticate. This avoids the user having to manually enter
this information.
The provisioning agent parses the provisioning file and provides the necessary information to Windows
Connection Manager. Windows automatically connects to these networks when they are available.
Credential generation
If the mobile broadband app generates or retrieves WISPr credentials in a proprietary manner during the
connection, the provisioning metadata includes a reference to the app, rather than providing specific credentials.
If specific credentials are included, this phase is skipped.
1. The captive portal website in the Wi-Fi hotspot includes a challenge from the Wireless Internet Service
Provider roaming (WISPr) protocol.
2. If static credentials were not provided, Windows Connection Manager notifies System Event Broker that
hotspot authentication is occurring. Otherwise, Windows Connection Manager proceeds directly to
authentication.
3. For proprietary authentication schemes, the System Event Broker invokes the mobile broadband app to
generate credentials.
4. The app generates credentials using its proprietary mechanisms. These may or may not involve
interaction with network resources, or with the mobile broadband interface. The app ultimately takes one
of the following actions:
Provide Credentials -- The app can generate credentials for this network, and then return them
to Windows Connection Manager. Windows Connection Manager authenticates to the hotspot
using WISPr.
Cancel Connection -- The PC should not be connected to this network. Windows Connection
Manager ends the connection.
Cancel Authentication -- The app has been authenticated by using an alternate method.
Windows Connection Manager will neither authenticate nor disconnect.
Interact with User -- The app is brought to the foreground. This is selected when user
confirmation is needed, such as a pay-per-connection hotspot. The app should ultimately take one
of the previously listed actions after consulting the user.
Authentication
When credentials are supplied by the mobile broadband app (dynamic WISPr credentials) or statically defined as
part of provisioning (static WISPr credentials, EAP credentials), Windows delivers these credentials to the Wi-Fi
hotspot.
The configuration information provided by the mobile broadband app to the connection profile in Windows
Connection Manager determines how credentials are obtained and delivered. The delivery is outlined in the next
steps:
1. When the user is in range of the Wi-Fi hotspot, Windows Connection Manager replies with credentials
that are statically defined by using provisioning metadata. This data can be generated by the mobile
broadband app, or through a trusted website.
2. The Wi-Fi hotspot verifies the credentials with the operator and then permits the PC to access the
Internet.
Displaying account information to the user
The best way for you to interact with your subscribers in Windows 8, Windows 8.1, and Windows 10 is by using
a mobile broadband app. This app is developed by you to meet your key scenarios around subscriber
interaction.
1. Windows determines which MNO or MVNO the subscriber belongs to when a mobile broadband device
is detected on the PC. The operator’s service metadata is matched and downloaded using by WMIS.
2. The service metadata links the mobile broadband app to the corresponding network entry in Windows
Connection Manager.
3. Windows Connection Manager shows the operator’s logo, operator name, and a View my account link.
4. When the user clicks the link, the mobile broadband app is opened. The app can be developed to retrieve
the most up-to-date information available from your billing system.
5. Optionally, the app can query the local data counters for an estimate of usage since the billing system
was last updated. The app can use this data to display a near-real-time approximation of the user’s usage.
6. More scenarios can be developed into the mobile broadband app. For detailed examples and user
experience guidelines of key scenarios the mobile broadband app can enable, see Designing the user
experience of a mobile broadband app.
Enabling other devices and app scenarios
Windows 8, Windows 8.1, and Windows 10 provide a rich set of development tools and a flexible development
platform that you can advantage of by creating apps that highlight the value added services that make them
unique.
Privileged apps
Mobile Broadband APIs and interfaces, including Account Provisioning and SMS, are restricted to mobile
broadband apps. A list of privileged apps that have access to these privileged APIs must be declared in the
service metadata package that is submitted to the Windows Dev Center Dashboard.
Multiple PDP contexts
Windows 8.1 and Windows 10 support multiple PDP contexts to be active at the same time. This allows mobile
operators to provide differentiated scenarios to their customers. For more information about the scenarios that
are enabled by using multiple PDP contexts, see Developing apps using multiple PDP contexts.
Wireline operators
You can use PnP-X to expose non-mobile broadband devices as a UWP device app.
Devices such as DVRs, gateway routers, mobile hotspots, and phones can (while connected to the same Wi-Fi or
LAN network as the Windows 8, Windows 8.1, or Windows 10 PC) use PnP-X to make Windows 8, Windows 8.1,
and Windows 10 aware of their presence. Device metadata is downloaded for those devices based on their
device properties and a UWP device app developed by you is automatically downloaded. You can reference this
app for these devices so that a single mobile broadband app can manage mobile broadband as well as these
additional devices.
How it works
The components that support the key scenarios for mobile broadband in Windows 8, Windows 8.1, and
Windows 10 are discussed in this section. They are divided between those that are part of the Windows
operating system and those that are part of the service metadata or mobile broadband app.
Windows components
The following components are part of Windows 8, Windows 8.1, and Windows 10:
Provisioning Agent
Data Usage and Subscription Manager
Windows Connection Manager
Local Data Counters
Mobile Broadband Service
Mobile Broadband Class Driver
System Event Broker
Windows Metadata and Internet Services
Microsoft Store
Provisioning Agent
The Provisioning Agent provides an interface for you to configure Windows with your network settings. The
Provisioning Agent accepts an XML file that describes the desired configuration.
You can provide the XML file in one of the following ways:
A signed XML file provided by a website to the window.external.msProvisionNetworks function on a
Windows 8, Windows 8.1, or Windows 10 computer running at least Internet Explorer 10 (or another
supporting browser).
An XML file (either signed or unsigned) provided by an app to the
Windows.Networking.NetworkOperators.ProvisioningAgent.ProvisionFromXmlDocumentAsy
nc function.
For more details about the format and content of the provisioning file, see Using metadata to configure mobile
broadband experiences.
Data Usage and Subscription Manager
The Data Usage and Subscription Manager tracks details about the user’s accounts. The stored cost information
about the currently connected network is available to all UWP apps. You can update this information by using
the Provisioning Agent.
If the carrier requests it, the Data Usage and Subscription Manager uses local data counters to trigger a
background event when 5 percent of the data limit has been used. The System Event Broker delivers this
background event and the mobile broadband app can use the event as a trigger to update billable usage.
Windows Connection Manager
Windows Connection Manager monitors available networks across Wi-Fi, mobile broadband, and Ethernet. It
makes automatic connect and disconnect decisions based on the available networks. The Provisioning Agent
enables you to define the relative priority between networks that you own. However, the user can manually
connect to any network. Windows Connection Manager uses the user’s manual actions to influence future
automatic connection choices.
Windows Connection Manager also manages post-connect authentication with Wi-Fi hotspots that support
WISPr 1.0. If static credentials have been stored for the Wi-Fi hotspot, Windows Connection Manager will
authenticate automatically. If dynamic credentials are required, Windows Connection Manager triggers a
background event by using System Event Broker. The mobile broadband app should then generate appropriate
credentials and deliver them to Windows Connection Manager in order to complete the authentication process.
For more details, see Integrating Windows with wireless hotspots.
Local Data Counters
Local data counters track the amount of data that is sent and received on a network interface over time. This
information appears to the user in multiple locations:
The App Histor y tab in Task Manager
(Optionally) Windows Connection Manager in the expanded view of the Wi-Fi or mobile broadband
network. Users can decide whether to show or hide this estimate for a particular network. By default, it is
shown for Mobile Broadband networks and hidden for Wi-Fi networks. However, if Windows detects that
a mobile broadband device is installed, it will hide estimated data usage in Windows Connection
Manager for the corresponding Mobile Broadband network. This is because there is an assumption that if
you have created a mobile broadband app, you will want to control the data usage value that is displayed
to the user. The best place to do that is inside the mobile broadband app. Users can choose to override
this behavior and show estimated usage for the network at any time.
Local data counters are also available programmatically by using the following APIs:
The Windows.Networking.Connectivity.ConnectionProfile.GetNetworkUsageAsync function
provides the data usage over a specified time period.
The Windows.Networking.Connectivity.ConnectionProfile.GetConnectivityInter valsAsync
function provides the connect timestamps and durations when a network interface is used.
Local data usage information serves as an estimate and a guide for the user. Windows cannot account for
unbilled traffic or for usage on other devices that share the same data limits. For example, family plans using the
same SIM on different devices. Mobile broadband apps should use local data counters only to approximate
usage since the last sync with your billing system. For data usage that has already been processed, the billing
system should be considered authoritative.
Mobile Broadband Service
The Mobile Broadband service is a Windows service that manages communication between the Mobile
Broadband APIs and a mobile broadband device. The service can interact with any mobile broadband device
whose driver conforms to the Windows Mobile Broadband Driver Model.
The service also reads the SIM of a newly inserted device and initiates the process that retrieves the service
metadata and the mobile broadband app that corresponds to the attached mobile broadband device.
Mobile Broadband Class Driver
The Mobile Broadband class driver reduces the burden on device manufacturers to deliver a custom driver for
their specific mobile broadband device. Any mobile broadband interface that manifests as a USB device and
complies with the USB Implementers Forum (USB-IF) Network Control Model (NCM) 2.0 specification will be
managed by the Mobile Broadband class driver and does not require additional drivers to be downloaded or
installed.
The Mobile Broadband class driver conforms to the Windows Mobile Broadband Driver Model and provides full
functionality to the Mobile Broadband service. It also supports custom extensions, which will be exposed directly
to the mobile broadband app. For more information, see Mobile operator hardware overview.
System Event Broker
The System Event Broker manages background events. Apps, including the mobile broadband app, can register
to receive background events in order to respond to changes in system state. Events that could be of interest to
the mobile broadband app include:
Network status change – Network connected or disconnected or Internet connectivity changed on a
network.
Account status change – End of billing cycle or 5 percent estimated data usage increments.
Wi-Fi hot-spot authentication – Attempting to connect to a public Wi-Fi hotspot and credentials are
needed.
Incoming operator notification – SMS/USSD message that matches certain parsing rules that
describe the SMS/USSD as coming from the operator.
Incoming SMS – SMS message received that does not match operator-defined parsing rules.
Incoming USSD – USSD message received that does not match operator-defined parsing rules.
Developers should be aware that a strict limit is placed on the amount of CPU time that an app may consume
while it is not active. Although these limits are relaxed for some events, apps must always minimize the
resources that they consume while the system is in a low-power state or while another app is running.
Windows Metadata and Internet Services
Windows Metadata and Internet Services (WMIS) is a cloud-based Windows service that delivers customizations
to Windows from third parties that participate in the Windows device ecosystem. For a mobile broadband
device, WMIS delivers the service metadata package. This provides the basic information that Windows needs in
order to retrieve the mobile broadband app from the Microsoft Store, allow connectivity to the network for the
first time, and display appropriate branding elements in Windows Connection Manager.
Microsoft Store
The Microsoft Store is the primary way that UWP apps are delivered to Windows 8, Windows 8.1, and
Windows 10 PCs. For a mobile broadband app, the app package is retrieved from the Microsoft Store whenever
Internet connectivity is available after the device is connected. The app package is automatically installed and
available to the user at that point. In Windows 8.1 and Windows 10, the app is available in All Apps but is not
automatically pinned to the Start screen.
For more information about UWP device apps, see UWP device apps.
Note Although enterprises can side load UWP apps under certain conditions, these will not be covered in this
document.
Operator metadata
Metadata about operators is provided in three different ways for Windows 8 and Windows 10 as described
below. Each of the metadata options targets a different set of customers. Understanding how the three types of
metadata are delivered and what information is used in each will help you better address your customers.
For more information about the operator metadata, see Using metadata to configure mobile broadband
experiences.
Windows APN database
The Windows APN database is present on all Windows 8, Windows 8.1, and Windows 10 PCs. The database is
periodically updated by using Windows Update to help ensure accuracy of the connectivity information. Updates
to the database are doing through servicing requests by you. The APN database provides information to
Windows about how to connect to the network if it encounters a Mobile Broadband device, including the APNs
to which it should attempt a connection and the URL to which the user should be directed if no Internet
connectivity is available.
This information is intended to get customers online within seconds of connecting a mobile broadband device. It
should enable them to purchase service immediately by using a Web browser or get online immediately if they
have already purchased service.
For information on submitting updates to the Windows APN database, see COSA/APN database submission.
Service metadata
Service metadata is delivered to any user after they connects a mobile broadband device. Service metadata is
always automatically downloaded as long as the user has any form of Internet connectivity, including metered
mobile broadband or roaming networks.
This information enables customers to have a richer experience by allowing you to add branding elements for
Windows Connection Manager, referencing a mobile broadband app that is automatically acquired from the
Microsoft Store, and having the most current mobile broadband settings for getting online for purchase or
Internet connectivity. Windows will periodically check that it has the latest service metadata package from
WMIS.
The service metadata package is delivered to customers only when a mobile broadband device from the
specified operator is detected on the PC. Information in this package overrides the content of the APN database,
whenever it’s present. For more information on the service metadata package schema reference, see Service
metadata package schema reference.
For instructions on how to create a service metadata package, see Developer guide for creating service
metadata.
Provisioning metadata
Provisioning metadata is delivered to the PC by either the operator’s website or the mobile broadband app after
the subscriber has purchased service. Provisioning metadata is packaged as an XML file and is processed by the
Provisioning Agent to modify the network settings of the PC.
Provisioning metadata can be specified for each subscriber’s individual requirements. The provisioning
metadata may also be updated with much higher frequency by using the mobile broadband app. Information in
the provisioning metadata overrides the contents of the APN database and the service metadata. This is because
it tends to be the most specific and tailored information about the subscriber.
Overview of mobile broadband Windows Runtime
APIs
4/13/2022 • 4 minutes to read • Edit Online
The following table lists the APIs for authoring a mobile broadband app.
Connection Profile API Provides information about the connection status (for
example, to the Internet)
Device Services Extension API Enables device-specific extensions, such as SIM Toolkit
and Preferred Roaming List (PRL) download.
SIM PIN API Enables you to enable, disable, or change the SIM PIN.
Subscriber and Device Information API Provides subscriber information for the SIM and device
information for the mobile broadband device.
For more information on the <Capabilities> element, see App Manifest File For Windows 8.
Note Applications that are not UWP apps (for example, Microsoft Win32 services or desktop apps) have
unrestricted access to the Mobile Broadband Account API. This is because these applications can use existing
Win32 and Component Object Model (COM) APIs to get full access to the mobile broadband network. These
APIs cannot be used from UWP apps.
Related topics
Mobile broadband WinRT API overview
Connection Profile API
4/13/2022 • 2 minutes to read • Edit Online
Related topics
List of mobile broadband Windows Runtime APIs
Network Information sample
NetworkStatusChangedEventHandler delegate
Device Services Extension API
4/13/2022 • 2 minutes to read • Edit Online
Windows-compliant mobile broadband devices project each supported feature as a device service. Examples of
services are IP Connectivity (ability to connect to or disconnect from a mobile broadband network), Phonebook,
SIM Toolkit, SMS, and USSD. Each device service has a corresponding GUID. All control messages and non-IP
packets that are exchanged between the mobile broadband generic driver and the device carry the GUID to
identify the service that is associated with the request. Command identifiers (CIDs) and status indication codes
are defined under a service’s GUID namespace. For example, Phonebook and SIM Toolkit might both share the
same CID code, but they are distinguished by the device service GUID that is exchanged in the request.
Any device services that are not natively implemented by the Windows wireless platform can be accessed by the
Device Services Extension API. This API provides a direct pipe for the independent hardware vendor (IHV)
software to access functionality on the device. This pipe provides a conduit through the WWAN service and
mobile broadband generic driver to the device, as shown in the following diagram:
The Windows wireless platform supports APIs for the following app functions:
Enumerate device services
Open/close device services
Send control commands to a specific device service
Send data to (or receive data from) a specific device service
Register for “unsolicited” device events from a specific device service
Related topics
List of mobile broadband Windows Runtime APIs
Provisioning API
4/13/2022 • 2 minutes to read • Edit Online
By using the Provisioning API, you can provision the Windows-based computer with required connection
profiles for mobile broadband and Wi-Fi, and can configure the cost that is associated with the mobile
broadband profiles. Provisioning information is contained in an XML document, as described in Using metadata
to configure mobile broadband experiences. You typically call this API after subscription purchase or to update
provisioning information on the computer.
You can also call the Provisioning API at any time to update the information that is provided to Windows. This is
usually done when the mobile broadband app retrieves updated cost and plan status from the operator’s server,
but it can also be done when Wi-Fi hotspot networks or the mobile broadband network configuration must be
updated.
For more information about the Provisioning API, see ProvisioningAgent class .
Related topics
List of mobile broadband Windows Runtime APIs
SIM PIN API
4/13/2022 • 2 minutes to read • Edit Online
By using the SIM PIN API, your mobile broadband app can support operations that are related to the SIM PIN
and the Pin Unlock Key (PUK).
For more information about the SIM PIN API, see Mobile Broadband API Interfaces.
Related topics
List of mobile broadband Windows Runtime APIs
SMS API
4/13/2022 • 2 minutes to read • Edit Online
Windows provides the SMS API to receive operator overage and roaming notifications, send and receive user-
to-user messages, and control the messaging configuration.
The SMS API supports the following use cases:
Send new SMS and new operator SMS notifications.
Send and read messages in text mode and Protocol Data Unit (PDU) mode (binary).
Get messages from the message store of the mobile broadband device.
Delete messages from the message store of the mobile broadband device.
Get properties of the mobile broadband device (account phone number, Global System for Mobile
communication [GSM] or Code-Division Multiple Access [CDMA], and similar information).
For more info about the SMS API, see Windows.Devices.Sms namespace .
Related topics
List of mobile broadband Windows Runtime APIs
Subscriber and Device Information API
4/13/2022 • 2 minutes to read • Edit Online
The Subscriber and Device Information API provides the following subscriber and device information to the
mobile broadband app:
Device name Name of the device.
Technology GSM, CDMA, and similar information.
Subscriber and device ID Subscriber and device identification information (IMSI, IMEI, electronic serial
number [ESN], and similar information).
Manufacturer Manufacturer of the device.
Mobile number Mobile number associated with the device.
SIM ID ICCID associated with the SIM.
Device capabilities Device interface capabilities, such as GSM Band Class and CDMA Band Class.
Firmware and hardware version Firmware and hardware version.
For more info about the Subscriber and Device Information API, see
Windows.Networking.NetworkOperators namespace .
Related topics
List of mobile broadband Windows Runtime APIs
USSD API
4/13/2022 • 2 minutes to read • Edit Online
The Windows USSD API is an abstraction of the underlying Unstructured Supplementary Service Data (USSD)
protocol, which hides most of the details to simplify app development. This API enables mobile broadband apps
to send USSD strings to a new or existing session or to cancel an existing session. This API supports notifications
from the network that may or may not require a response. A response is required for a network-initiated USSD
request or when further information is needed after a mobile-initiated operation.
For more info about the USSD API, see Windows.Networking.NetworkOperators namespace .
Related topics
List of mobile broadband Windows Runtime APIs
Create a MobileBroadbandAccount object
4/13/2022 • 2 minutes to read • Edit Online
Because the MobileBroadbandAccount objects represent network accounts, a network account ID is needed
to create such an object. When a mobile broadband app is started from the network list, it receives the network
account ID to use as a parameter to the tile launch contract.
If the app is activated directly from its tile, there are no parameters associated with the tile launch contract, and
you must get the value of the AvailableNetworkAccountIds static property of the
MobileBroadbandAccount class. This returns a read-only collection of strings, in which each string is a single
account ID. If this method returns a collection that has a single string, you don’t need to take any further action.
The following JavaScript code example shows how to do this:
var myNetworkAccountId;
var allNetworkAccountIds =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.availableNetworkAccountIds;
if (allNetworkAccountIds.size == 1)
{
myNetworkAccountId = allNetworkAccountIds[0];
}
If the returned collection contains more than one string, you will need input from end user who is running the
application. One way is to iterate through the collection, creating a MobileBroadbandAccount object for each
account ID in the collection, and then use a property of the object (for example, the telephone number) to
populate a list box control. This control is presented to the end user, and after the user makes a selection, all
other MobileBroadbandAccount objects can be released.
After you have the account ID, call the CreateFromNetworkAccountId static method of class
MobileBroadbandAccount . The following code example shows how to do this by using JavaScript:
MobileBroadbandAccount.AvailableNetworkAccountIds returns an
empty list
If your app is not trusted, the property returns an empty collection instead of throwing an exception because
users can have accounts from more than one network operator on their computer. The
AvailableNetworkAccountIds property returns only those account IDs that the app’s metadata package is
allowed to see. Because the AvailableNetworkAccountIds property checks that each account ID has a device
associated with it at the time it is retrieved, this property can return an empty collection even if
CreateFromNetworkAccountId does not throw an Access Denied exception.
This can happen if no network hardware is detected, or if the network hardware does not have an accessible
SIM. A simple way to determine the exact reason why the returned collection is empty is to look at the WWAN
logs. After you have collected the logs, search the text log file for entries that contain the text
AvailableNetworkAccountIds .
Create a MobileBroadbandDeviceInformation
object
4/13/2022 • 2 minutes to read • Edit Online
A MobileBroadbandDeviceInformation object contain a set of properties that you can use to obtain mobile
broadband–specific data about the network device that is associated with a mobile broadband account (for
example, the firmware version). You can obtain these objects from a MobileBroadbandAccount object only.
Note that a single MobileBroadbandAccount object can be associated with multiple
MobileBroadbandDeviceInformation objects, but only one at a time. (This will happen if a single SIM card,
which holds the information that the MNO uses to differentiate user accounts, is used in two different mobile
broadband devices.)
You get MobileBroadbandDeviceInformation objects by getting the CurrentDeviceInformation property
of a MobileBroadbandAccount object. If there is no network device present at the time that the
CurrentDeviceInformation property was read (for example, because it was unplugged or turned off), reading
this property will return NULL. Because this can change at any time (for example, the user can unplug the
device), we recommend that you get a copy of the property, test that for NULL, and use the copy. The following
code example illustrates shows how to do this:
if (myDeviceInfo == null)
{
// no device present, inform user
}
else
{
// use myDeviceInfo to get the data you need
}
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Create a MobileBroadbandNetwork object
4/13/2022 • 2 minutes to read • Edit Online
MobileBroadbandNetwork objects contain a set of properties that you can use to obtain live data about the
network that is associated with a mobile broadband account (for example, the network registration state or the
APN). You can obtain these objects from a MobileBroadbandAccount object only. Note that a single
MobileBroadbandAccount object can be associated with multiple MobileBroadbandNetwork objects, but
only one at a time. (This will happen if a single SIM card, which holds the information that the MNO uses to
differentiate user accounts, is used in two different mobile broadband devices.)
You obtain MobileBroadbandAccount objects by getting the CurrentNetwork property of a
MobileBroadbandAccount object. If there is no active network at the time that the CurrentNetwork
property was read (for example, because the network device was unplugged or turned off, or the radio had no
signal), reading this property will return NULL. Because this can change at any time (for example, the user can
walk into an elevator with the computer, causing the connection to drop), we recommend that you get a copy of
the property, test that for NULL, and use the copy. The following code example illustrates this.
if (myNetwork == null)
{
// no network, inform user
}
else
{
// use myNetwork to get the data you need
}
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Determine if a device is PIN-locked
4/13/2022 • 2 minutes to read • Edit Online
Because the subscription information on a locked device (for example, ICCID or IMEI) might not be available, all
locked devices enumerate an available network account. To know whether an account represents a locked
device, query the NetworkDeviceStatus property of the CurrentDeviceInformation property for the
account. NetworkDeviceStatus .DeviceLocked indicates a PIN lock, whereas
NetworkDeviceStatus .DeviceBlocked indicates a PUK block.
For example:
var account =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.createFromNetworkAccountId(accountId);
if (account.currentDeviceInformation.networkDeviceStatus ==
Windows.Networking.NetworkOperators.NetworkDeviceStatus.DeviceLocked)
{
// the pin is locked
}
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Determine which mobile broadband network is
currently connected
4/13/2022 • 2 minutes to read • Edit Online
You can determine which mobile broadband network you’re connected to by retrieving the APN through the
AccessPointName property of the current network object for the account.
For example:
account.currentNetwork.accessPointName
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Determine which Windows device is being used to
connect to the network
4/13/2022 • 2 minutes to read • Edit Online
To determine which Windows device is being used to connect to the network, check the Windows device ID for
the network adapter, which is exposed by the DeviceId property of the current network device object for the
account.
For example:
account.currentDeviceInformation.deviceId
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Discover whether the network device radio is turned
on
4/13/2022 • 2 minutes to read • Edit Online
If the user starts the mobile broadband app directly from its tile, the mobile broadband device might be turned
off. This will usually happen if the device entered a power-saving mode or the end user turned on airplane mode
(which disables the network devices). If this is the case, getting the CurrentRadioState property of the
MobileBroadbandDeviceInformation object for the network device in question will return
MobileBroadbandRadioState .Off . (Alternatively, if the radio is turned on, the CurrentRadioState property
will return MobileBroadbandRadioState .On .)
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Enumerate available mobile broadband accounts
4/13/2022 • 2 minutes to read • Edit Online
There are two methods that you can use to enumerate network accounts: polling or event-based.
Polling The mobile broadband app can poll for available network accounts by using the static
MobileBroadbandAccount.AvailableNetworkAccountIds method. This is ideal if the application
simply needs a snapshot of the accounts and does not need to respond at run time to accounts that are
being added or removed.
Event-based You can use the MobileBroadbandAccountWatcher class to enumerate and then
monitor for changes to mobile broadband accounts. The event-based method is ideal when the
application must respond to changes (that is, return to the account selection page when the currently
selected account is removed). The procedure to use this class is as follows:
1. Instantiate a MobileBroadbandAccountWatcher object.
2. Add event handlers to the AccountAdded , AccountRemoved , and EnumerationCompleted
events.
3. Invoke Start() on the watcher.
The AccountAdded event handlers are invoked for each existing network account. When all of the
existing network accounts are enumerated, the EnumerationCompleted event is raised.
Additional AccountAdded and AccountRemoved events are raised as account availability changes
(that is, when mobile broadband hardware or the SIM is removed).
Impor tant Account watcher objects automatically stop when the app is suspended by Windows, and restart
when the app is resumed. This is done to preserve battery life because resuming a suspended app to process an
event and then putting it back in the suspended state can result in significant disk activity. The Stopped event
occurs when the watcher stops (this happens either right before or right after the app gets its Suspending
event). When the app resumes, all watchers that were running before the app was suspended automatically
restart, thereby triggering a series of AccountAdded events that are followed by an EnumerationCompleted
event (the same way as if the Star t method had been called). This enables the app to get up-to-date with
anything significant that occurred during the time that it was suspended.
MobileBroadbandAccountWatcher objects are independent of each other. This means that you cannot
depend on all watchers reporting the same set of events – as a group, they will report all events. However, any
given watcher might not report any given event, because that event has been consumed by another watcher.
Unless you have good reason, you should use only one account watcher object per app.
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Establish temporary network connectivity
4/13/2022 • 2 minutes to read • Edit Online
Telecommunication applications cannot initiate long-term connections. However, if you need temporary
connectivity to a specific network, you can use the Mobile Broadband API as follows:
1. Create an instance of IMbnConnectionManager .
2. Register to the IMbnConnectionEvents connection point.
3. Create an instance of IMbnInterfaceManager .
4. Get an IMbnInterface interface for the device by passing the account device ID into
IMbnInterfaceManager ::GetInterface . (For more info, see Unlock a device.)
5. Obtain an IMbnConnection interface for the device by calling
IMbnConnectionManager ::GetConnection .
6. Establish a connection by calling IMbnConnection::Connect . The connectionMode parameter must be
set to MBN_CONNECTION_MODE_TMP_PROFILE , and the strProfile parameter must be a mobile
broadband profile description.
The results of the connect attempt are returned by using the IMbnConnectionEvents::OnConnectComplete
method. To disconnect when you are finished, invoke the IMbnConnection::Disconnect method. Status is
returned by using IMbnConnectionEvents::OnDisconnectComplete .
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Get information about the currently registered
network
4/13/2022 • 2 minutes to read • Edit Online
You can get the data class, service provider ID and name of the network that the mobile broadband device is
currently registered to. To do this, use the RegisteredDataClass , RegisteredProviderId , and
RegisteredProviderName properties of the current network object for the account.
For example:
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Get the IMEI, ICCID, IMSI and telephone numbers
for the mobile broadband device
4/13/2022 • 2 minutes to read • Edit Online
The following properties are available for the current network device for the account:
IMEI MobileEquipmentId
MEID MobileEquipmentId
IMSI SubscriberId
MIN SubscriberId
IRM SubscriberId
ICCID SimIccId
account.currentDeviceInformation.mobileEquipmentId
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Know when network connectivity changes
4/13/2022 • 2 minutes to read • Edit Online
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Open the networks list
4/13/2022 • 2 minutes to read • Edit Online
You can open the networks list by calling the ShowConnectionUI method of the current network object for the
account.
For example:
account.currentNetwork.showConnectionUI()
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Receive notification for device information account
changes
4/13/2022 • 2 minutes to read • Edit Online
To receive a notification for device information account changes, use the AccountUpdated event of
MobileBroadbandAccountWatcher as described here:
1. Instantiate a MobileBroadbandAccountWatcher object.
2. Add an AccountUpdated event handler.
3. Invoke Star t on the watcher.
4. Query the HasDeviceInformationChanged property of the
MobileBroadbandAccountUpdatedEventArgs object in the AccountUpdated event handler.
5. If the device information has changed, query the account
CurrentDeviceInformation.TelephoneNumbers property for the telephone number.
For example:
if (account.currentDeviceInformation.TelephoneNumbers.length > 0)
{
// there is now at least one telephone number
}
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Receive notification when mobile broadband
accounts are added or removed
4/13/2022 • 2 minutes to read • Edit Online
For more info on receiving notifications when mobile broadband accounts are added or removed, see the event-
based enumeration method in Enumerate available mobile broadband accounts.
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Retrieve ConnectionProfile objects for a
MobileBroadbandAccount
4/13/2022 • 2 minutes to read • Edit Online
A ConnectionProfile object contains a set of properties and methods that you can use to obtain connectivity,
usage, and data plan information for established network connections. The connection profiles associated with a
mobile account can be retrieved by using the MobileBroadbandAccount object. The following code example
illustrates shows how to do this:
Note A list of all ConnectionProfile objects can be retrieved from
Windows.Networking.Connectivity.NetworkInformation.GetConnectionProfiles .
if (myConnectionProfileList.length !== 0)
{
for (var i = 0; i < myConnectionProfileList.length; i++)
{
//Display connection profile properties
var connectivityLevel = myConnectionProfileList[i].getNetworkConnectivityLevel();
}
}
else
{
// No connection profiles are associated with this mobile broadband account.
}
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Unlock a device
4/13/2022 • 2 minutes to read • Edit Online
A subset of the mobile broadband API includes the PIN Management API. To unlock a device, do the following:
1. Get the network adapter ID for the account device:
account.currentNetwork.networkAdapter. networkAdapterId
Related topics
Common tasks for mobile broadband Windows Runtime APIs
Best practices for handling account arrival and
removal events
4/13/2022 • 2 minutes to read • Edit Online
Mobile broadband accounts can be added or removed during the lifetime of the mobile broadband app. This can
be caused by the addition or removal of hardware, PIN unlocking, or SIM swapping. The arrival or removal of an
account is transient in many cases. Proper handling of these events has significant implications on the usability
of the application. The following best practices apply to handling account arrival and removal events:
Do not immediately raise an error dialog when the active account that is being used is removed.
Do not assume that the user has removed the hardware. Hardware might be temporarily unavailable
during sleep/resume of the machine, depending on the behavior of the driver or the bus.
Do not release any started account watcher objects without calling their Stop method first. Account
watchers, like all Windows Runtime (WinRT) objects, are reference counted. Calling Star t increments
their reference count (Stop decrements it). If you release a started account watcher, it will keep triggering
events but you cannot call Stop on the handle that you’ve just released.
Remember that account watcher objects automatically stop when the app gets suspended by Windows,
and restart when the app resumes. This is the same result as if your app had called Stop and Star t , and
results in the same events. Use these events to bring the app up-to-date with anything significant that
occurred during the time that it was suspended.
Related topics
Best practices for using Mobile Broadband Windows Runtime API
Best practices for connecting to the mobile
broadband network
4/13/2022 • 2 minutes to read • Edit Online
Active connections to the mobile broadband network can be an unnecessary drain on battery life and account
data quotas. We recommend that you use careful judgment to determine whether a connection is necessary.
Use the following best practices regarding connectivity to the mobile broadband network:
Do not use the provisioning agent’s <Activation> directives. These directives are intended only for
specific circumstances after activation.
Use the Mobile Broadband API to establish temporary connectivity. This API provides connection
operation results and an easy way to disconnect.
Keep the connection lifetime to a minimum.
Use connectivity through Internet-connected interfaces whenever they are available. You can observe
availability by using the NetworkInformation API.
Related topics
Best practices for using Mobile Broadband Windows Runtime API
Mobile operator hardware overview
4/13/2022 • 13 minutes to read • Edit Online
You should use this topic to get a high-level understanding of the Windows 8, Windows 8.1, and Windows 10
mobile broadband hardware requirements and recommendations. We recommend the following to provide
your customers with a simplified connection experience, as well as reducing your maintenance and support
costs.
Embedded mobile broadband modules that provide USB interfaces must meet the Windows 8,
Windows 8.1, or Windows 10 hardware certification requirements and be managed by using the mobile
broadband class driver. Your hardware requirements documentation for IHVs should require that mobile
broadband devices pass the Windows 8, Windows 8.1, or Windows 10 device certification.
External USB mobile broadband dongles must support identity morphing. Your hardware requirements
documentation for IHVs should require that external mobile broadband devices pass both the Windows 8
device certification, Windows 8.1, or Windows 10 device certification and pass the Windows 7 logo
certification.
On a Windows 10 computer, the dongle appears as a Windows 10 certified mobile broadband
device and is managed by using the mobile broadband class driver.
On a Windows 8.1 computer, the dongle appears as a Windows 8.1 certified mobile broadband
device and is managed by using the mobile broadband class driver.
On a Windows 8 computer, the dongle appears as a Windows 8 certified mobile broadband device
and is managed by using the mobile broadband class driver.
On a Windows 7 computer, the dongle appears as a mass storage device, allowing the user to
install specific device drivers.
If you require EAP-SIM, USSD, or multiple PDP connections, the IHV must enable it and it must comply
with the Windows 8, Windows 8.1, or Windows 10 hardware certification requirements.
Any additional functionality required by you or the IHV must be implemented using the device services
extension and enabled in Windows 8, Windows 8.1, or Windows 10 by using the mobile broadband class
driver and the Device Services APIs. You should include any additional functionality as part of your
hardware requirement documentation.
Key scenarios
Purchase an external device
An external device is likely to be inserted immediately before the user wants to begin using it.
1. As soon as the device is inserted, it is recognized and managed by the mobile broadband class driver.
2. The Mobile Broadband Service reads the IMSI and generates a set of hashes.
3. When the user clicks Connect , these hashes are used to match connection settings within the COSA/APN
database submission.
If the connection is successful and Internet connectivity is available, nothing further happens. The
user has already purchased service.
If the connection is successful, but Internet connectivity is not available, the web browser opens to
the URL specified in the APN database or your UWP mobile broadband app.
If the connection fails, the user is notified of the error.
4. Your web site or your mobile broadband app helps the user purchase service.
5. After purchase, the device is provisioned by using the provisioning API from a provisioning file. The
provisioning file is passed to the provisioning agent by the web site or the mobile broadband app. The
provisioning file configures Windows with basic information about the plan that the user has purchased.
Depending on the network structure, one of the following occurs:
The user is granted Internet access on the current connection.
The provisioning file includes instructions to disconnect and reconnect to the same network or a
different network, which will provide Internet access.
Connect an external device with an active SIM
When an active device is attached that already had an active SIM, the workflow is similar to when you purchase
an external device, except that the attempted connection will lead to the Internet. You don’t need to direct the
user to your website or mobile broadband app to purchase service.
1. As soon as the device is inserted, it is recognized and managed by the mobile broadband class driver.
2. The Mobile Broadband Service reads the IMSI and generates a set of hashes.
3. When the user clicks Connect , these hashes are used to match connection settings within the COSA/APN
database submission. For a device with an active SIM, the connection is successful and Internet
connectivity is available.
Components
Windows 8, Windows 8.1, or Windows 10 certified mobile broadband devices
To take full advantage of the Windows mobile broadband platform, your mobile broadband device must meet
the Windows 8, Windows 8.1, or Windows 10 hardware certification requirements. For a comprehensive
description of the hardware certification requirements, see Windows Hardware Certification Requirements.
For the end user, the most simplified connection experience is delivered with a USB-based mobile broadband
device. As part of the hardware certification requirements, any mobile broadband device that manifests as a
USB device must comply with the Mobile Broadband Interface Model (MBIM) specification and the MBIM v1.0
Errata. This includes both external USB dongles and embedded modules that provide USB interfaces. For this
class of devices, Windows 8, Windows 8.1, or Windows 10 includes a mobile broadband class driver, which
eliminates the need for additional drivers from the IHV and simplifies the user’s connection experience. Other
hardware that is not USB and driver models can receive Windows 8, Windows 8.1, and Windows 10 certification
and will provide the Microsoft Store mobile broadband app experience, but these are not supported by the
mobile broadband class driver.
Mobile broadband class driver
The mobile broadband class driver reduces the burden on device manufacturers to deliver a custom driver for
their specific mobile broadband device. The mobile broadband class driver manages any USB MBIM-compliant
mobile broadband interface that meets the Windows 8, Windows 8.1, or Windows 10 device certification. When
a certified device is connected, no additional drivers are required and Windows can immediately use the device
to connect to your network. The mobile broadband class driver conforms to the Windows mobile broadband
driver model and provides full functionality to the Windows Mobile Broadband Service. It supports GSM
networks, including HSPA+ and LTE; CDMA networks; and dual-mode networks offering 3G CDMA and 4G LTE. It
also supports operator messages such as SMS and USSD, and EAP-SIM-based authentication.
Note While USSD, EAP-SIM, and multiple PDP contexts are supported by the mobile broadband class driver,
they are optional components of the Windows 8, Windows 8.1, or Windows 10 for desktop editions (Home, Pro,
Enterprise, and Education) hardware certification requirements. Multiple PDP contexts are required for
Windows 10 Mobile for hardware certification, however.
Additional device functionality can be implemented using custom device service extensions, which will be
exposed directly to the mobile broadband app through the WinRT Device Services API.
For more information on the mobile broadband class driver, see Mobile Broadband (MB) Reference.
Device service extension API
One of the distinct advantages to using the Windows platform is the ability to provide new hardware scenarios
that support operator differentiation. The Windows mobile broadband platform is expected to enable
differentiation for operators that can command higher customer loyalty and brand equity. The platform provides
a set of extension points that you can incorporate into your unique experience.
Windows certified mobile broadband devices declare each supported extension point as a “device service”.
Examples of such services include Phonebook, SIM Toolkit, or GPS features. Any device services that are not
natively implemented by the Windows mobile broadband platform can be accessed by using the Device Service
Extension API. You and the IHV define the device services that should be implemented. The IHV’s firmware and
your mobile broadband app must be designed concurrently to enable the desired device services. The USB
Implementers Forum is establishing a registry of device services that are available to IHVs at MBIMRegistry, and
we recommend that you and the IHVs you are working with use this registry to coordinate to ensure consistency
for common device services extensions.
The Device Service Extension API provides a direct way for the mobile broadband app to access functionality on
their mobile broadband device. This provides a conduit through the WWAN service and the mobile broadband
class driver to the device, as illustrated in the following diagram:
Each device service has a corresponding GUID. All control messages and non-IP packets exchanged between the
mobile broadband class driver and the device will carry the GUID to identify the service associated with the
request. Command identifiers (CIDs) and status indication codes are defined under a service’s GUID namespace.
For example, Phonebook and STK could both share the same CID code, but will be distinguished by the device
service GUID exchanged in the request.
Note The COM-based Device Services API is accessible to any desktop application or service. The WinRT
projected Device Services API is available only to a privileged UWP device app that is authorized by a mobile
broadband operator. Developers should carefully consider privacy and security when communicating
information this way.
The Windows wireless platform supports APIs for the following functionality that is available to apps:
Enumerate device services
Open and close device services
Send control commands to a specific device service
Send or receive data to or from a specific device service
Register for unsolicited device events from a specific device
For more information, see IMbnDeviceSer vice interface .
Legacy support and identity morphing
Windows 8, Windows 8.1, and Windows 10 support mobile broadband devices designed for Windows 7.
Whereas the current ecosystem of devices will continue to function on Windows 8, Windows 8.1, and
Windows 10 they will not fully utilize the Windows 8, Windows 8.1, or Windows 10 mobile broadband
platforms.
A summary of mobile broadband device support inWindows 8, Windows RT, Windows 8.1, and Windows RT 8.1
is provided here:
Windows 10 certified devices – These devices pass the mobile broadband experience tests supporting the
Windows 10 Hardware Certification Kit. For these devices, Windows 10 provides the mobile broadband
class driver and advanced power management.
Windows 8 or Windows 8.1 certified devices – These devices pass the mobile broadband experience tests
supporting the Windows 8 or Windows 8.1 Hardware Certification Kit. For these devices, Windows 8 and
Windows 8.1 provide the mobile broadband class driver and advanced power management.
Windows 7 logo’d devices – These devices use third-party IHV drivers based on Windows 7 NDIS 6.20
driver model. Windows 8 and Windows 8.1 provide mobile broadband experience in backward
compatibility mode for these devices and they are limited to Windows 7 functionality.
Windows 8 and Windows 8.1 will continue to support the legacy devices based on modem or Ethernet
interfaces along with a custom connection manager as in earlier versions of Windows. Windows 8 and
Windows 8.1 will not be able to provide mobile broadband experiences as they are not compliant with
the mobile broadband stack. Because the legacy devices are not recognized by the mobile broadband
stack, connectivity over such devices may result in excessive data consumption as they are not managed
by Windows Connection Manager.
Windows RT and Windows RT 8.1 certified devices – These devices pass mobile broadband experience
tests supported by the Windows RT or Windows RT 8.1 Windows Hardware Certification Kit. For these
devices, Windows RT and Windows RT 8.1 provide the mobile broadband class driver and advanced
power management.
Note Windows RT and Windows RT 8.1 systems do not support mobile broadband devices designed for
Windows 7 and earlier versions.
To ensure that Windows 8 and Windows 8.1 certified devices are useful on older platforms, Windows provides
an identity morphing solution that enables the device to exhibit behavior that is appropriate for the operating
system to which it is connected.
Identity morphing
When the device is first connected to a Windows 7 PC, a typical external mobile broadband USB dongle presents
itself as a mass storage device. This does not expose other functionality to prevent these devices from appearing
as non-functional due to missing driver software. The mass storage device contains the IHV-supplied software
that installs the driver package. After the user installs the driver package, the IHV-supplied software must morph
the device to expose the other functions to the user. At this point, the device will appear as a mobile broadband
device and the user can connect to your network.
The native Windows 8, Windows 8.1, and Windows 10 class driver eliminates the need for an external USB
device to expose itself initially as a mass storage device, since no driver installation is necessary. Windows 8,
Windows 8.1, and Windows 10 include the capability to trigger a device’s identity morphing, allowing the device
to immediately appear as a mobile broadband device.
To learn how to develop an identity morphing solution, see IMbnDeviceSer vice interface .]
Firmware update support
Mobile broadband device firmware should be updated by using Windows Update. For info on how this can be
done, see Mobile Broadband Device Firmware Update on Windows 8. Specific configurations for your
experience can be provisioned by using your mobile broadband app.
OMA -DM client support
Windows 8.1 added OMA-DM support for enterprises to manage your devices running Windows in BYOD
(Bring Your Own Device) scenarios. This extends support for these scenarios by adding enterprise-relevant
protocols (MS-MDE, MS-MDM) for use by 3rd-party mobile device management providers and Windows
InTune.
Windows separates OMA-DM support for mobile Network operator configuration from the support for
enterprise BYOD. The OMA-DM client in Windows 8.1 and Windows 10 does not support configuring Mobile
Operator specific settings natively and is not 3rd party extensible to support mobile network operator
requirements. OMA-DM solutions supporting Windows Phone platform are not compatible with the
Windows 8.1 OMA-DM client or the Windows 10 OMA-DM client.
Here are some options to consider when supporting an operator-specific OMA-DM:
If the OMA-DM client is in the network adapter’s firmware:
Typically, mobile broadband device manufacturers may bundle operator-specific OMA-DM client in
their network adapter’s firmware.
The mobile broadband device manufacturer may be able to provide 3rd party OMA-DM client
solutions for integrating in their network adapter firmware if a natively supported solution does
not exist.
Mobile broadband apps should continue to use provisioning metadata when configuring
operating system specific parameters.
OMA-DM client in the mobile broadband app:
If the modules do not support an OMA-DM client in the network adapter’s firmware, you may
want to implement OMA-DM client in your mobile broadband app.
This solution requires operator-specific or device manufacturer-specific custom device service
support for configuring device specific parameters by the mobile broadband app.
Mobile broadband app that include an OMA-DM client should use provisioning metadata when
configuring operating system specific parameters.
APN Management
Default APN management is done by using the local APN database. You may desire to have the APN information
changed for selective users, such as enterprise users. In such cases, either you or the OEM can choose to update
the APN directly on the device by using OMA DM in OTA signaling.
Your device must implement the following:
When pre-provisioned by operator or provisioned through OTA prior to a successful connection by
using the SIM on that system, the device should provide Internet PDP context as a first provisioned
context with the ContextType set to Internet when queried by Windows as defined in MBIM section
10.5.13.5. This ensures that the connection logic uses this APN information when attempting a
connection.
If the SIM has been used to establish a successful connection to the network using an alternative APN on
that system, setting the ContextType to Internet will not work. The only way to force the Window to
establish a connection using the new APN is to delete the specific profile created. The profile can be
deleted by running the following command from an elevated command prompt: netsh mbn delete
profile interface="Mobile Broadband Connection" name="myProfileName"
Note Since this is an optional Windows feature for devices to support, there is no HCK test or automated test
case to validate this scenario on the system. It is our expectation that the operator certification will handle the
validation to confirm that the device conforms to the operator requirements.
For more info about the APN database, see APN database overview.
Network personalization
Certain operators require that mobile broadband-enabled systems be locked to its network or have
requirements to unlock a locked device to allow for service portability. To enable this scenario, we require the
OEM’s and device vendors use MBIM_PIN_TYPE guidance in the MBIM Specification for Subsidy Lock.
The device must report WWAN_READY_INFO :: ReadyState =WwanReadyStateInitialized in this locked
state and should not report WwanReadyStateDeviceLocked .
Note There is no HCK test case to validate that this feature implemented on the device or system works with
Windows. We look towards the OEM and the operator to use specific filters within MBOT to ensure that the final
product can be tested.
Overview of using metadata to configure mobile
broadband experiences
4/13/2022 • 2 minutes to read • Edit Online
IMPORTANT
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8, Windows
8.1, and versions of Windows 10 before 1703 will continue to use the APN database while Windows 10, version 1703 and
later use COSA. For more information about COSA, see COSA overview.
Starting in Windows 10, version 1803, the MBAE app experience is replaced by an MO Overview of UWP app. For more
information about MO Overview of UWP apps, see Overview of UWP mobile broadband apps.
You can provide metadata to customize various aspects of the Windows 8, Windows 8.1, and Windows 10
mobile broadband application experience. These include customizing Windows Connection Manager with
operator branding, integrating the mobile broadband app with Windows Connection Manager, providing
updated information for the Windows APN database, and providing data to provision the PC. Windows 8,
Windows 8.1, and Windows 10 includes three sources of metadata you can use:
Windows APN database The Windows APN database contains pre-provisioned data that is required to
connect to the operator's network for the first time. The database is part of Windows 8, Windows 8.1, and
Windows 10 and is updated by using Windows Overview of update. The Windows APN database is
always available on the PC. For more info about COSA and the APN database, see COSA/APN database.
Ser vice metadata Information required for subscription purchase and operator branding. You provide
this information as part of the service metadata package. It is stored on the Windows Metadata and
Internet Services (WMIS) and downloaded after a mobile broadband device is detected using any
available Internet connection. This metadata can also be preinstalled onto a PC by the OEM, but you must
preinstall the package that was downloaded from the hardware developer section of the Windows Dev
Center - Hardware. For more info about the service metadata, see Service metadata.
Account provisioning metadata Information generated after a subscription purchase, including Wi-Fi
credentials and plan information. This metadata is provided by you to Windows after payment validation
and can be updated by using the provisioning-refresh mechanism. For more info about the account
provisioning metadata, see Account provisioning.
The following diagram shows how the different metadata sources are related and how they are serviced. The
service metadata takes priority over information in the Windows APN database.
Overview of use the links in this section to learn more about the different types of mobile broadband metadata:
Account provisioning
COSA/APN database
Service metadata
Account provisioning
4/13/2022 • 24 minutes to read • Edit Online
Provisioning refers to configuring a Windows computer with the information that is required to connect to an
operator network. Provisioning is usually performed after a mobile broadband subscription purchase. Windows
accepts an XML-based provisioning file from the operator. The Provisioning API applies a provisioning XML file
from the operator, either by using a mobile broadband app or through a purchase web site.
The following diagram illustrates the contents and hierarchy of the provisioning XML file.
For more info about the provisioning schema, see CarrierControlSchema schema.
SubscriberId A string that uniquely identifies the customer in your organization. If you are a mobile
operator, this should be the IMSI or ICCID ranges for GSM operators or the provider ID or provider name
for CDMA operators. If you are not a mobile operator, you can choose any sufficiently unique string.
Activation
Device activation occurs after the activation process is complete on the back end. The PC might need to follow
certain instructions before connecting to the network. The provisioning engine uses the activation instructions
received in the device activation element. If no value is specified, then no client action is required. Available
actions include:
Re-connect Disconnect and connect to the operator network.
Re-register Disconnect and register to the operator network.
Data Data or instructions that you want to send to the device to activate the connection. The Provisioning
Engine passes this data as is to the device. For CDMA, this can include instructions such as *228 to start
an OTA Programming Session and reconnect to the network.
Mobile broadband information
Mobile broadband information contains several elements:
MBNProfiles
Defines subscriber information on the mobile operator network. There are two different profiles that can be
used:
PurchaseProfile : Information that is needed to connect to the operator’s network to purchase a new
subscription.
DefaultProfile Every mobile broadband subscription can have one default profile that is used to connect
to the home network operator. Windows Connection Manager uses this profile for auto-connecting to the
network.
<MBNProfiles>
<DefaultProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<Name>Contoso MBN</Name>
<Description>Contoso Mobile Broadband</Description>
<HomeProviderName>Contoso MBN</HomeProviderName>
<Context>
<AccessString>contoso.com</AccessString>
<UserLogonCred>
<UserName>mbuser</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
Branding
IMPORTANT
Starting in Windows 10, version 1709, branding fields provisioned by the ProvisioningAgent API have been replaced by
branding fields in the COSA database. Logo has been replaced by Branding Icon in COSA, and Name has been
replaced by Branding Name in COSA.
Logo and Name will no longer be considered when provisioning in Windows 10, version 1709 and later. The
ProvisioningAgent API will not throw an error if they are used, but you should change Branding Icon and Branding
Name in COSA instead.
For more information about Branding Icon and Branding Name , see Desktop COSA/APN database settings (Desktop
COSA only settings).
Branding lets you specify how Windows displays your mobile broadband networks. This information overrides
any service metadata, if present. If no information is provided, the contents of the service metadata package are
used. The branding elements are as follows:
Logo A Base64-encoded .PNG or.BMP file that is embedded in the XML. This logo is applied to your
mobile broadband profiles for display in the Network List.
Name Sets the carrier’s display name for the mobile broadband profiles.
SMS Parsing
You can provision the rules to identify a text message and extract information as part of the provisioning XML
file. You can use SMS messages to update data usage statistics or to initiate a refresh of provisioning
information. These messages can be identified by a combination of the following:
Bearer type (SMS/USSD)
Sender (SMS only)
Regular expression
For more information on SMS notifications, see Enabling mobile operator notifications and system events.
Each rule contains the following information:
Silent If this value is true, the message results in a MobileOperatorNotification event only. If this value is
false, the message results in an SmsMessageReceived event.
Allowed sender Specifies the reserved sender address from which the notification is permitted to
arrive. This number must exactly match the sender number that is received in the SMS message,
including the international format.
Pattern The regular expression to identify and optionally extract data fields from the text message. This
pattern will match all messages from a sender: [^]*
RuleId An identifier for this rule, which is passed to the mobile broadband app as part of the
MobileOperatorNotification event. This identifier enables the app to know which rule caused the SMS to
trigger a MobileOperatorNotification event, and can reduce the app’s need to parse the message again.
Fields and groups Each capturing group in the regular expression pattern is tied to a named field. This
is used to extract and transform the data into a set of usable values. For example, the first match-group
can be tied to the Usage field and the second match-group can be tied to the UsageDataLimit field.
This association indicates that the first value is the current usage information, and the second value is the
maximum allowed usage.
Usage, UsagePercentage, UsageOverage, UsageOveragePercentage : Expresses the current
usage as an absolute number, as a percentage of the data limit, as a number in excess of the data
limit, or as a percentage in excess of the data limit. Absolute values can reference a group that
specifies the unit in which the value is expressed.
UsageTimestamp : The date and time at which the usage field is calculated. This information must
be included if any Usage\ * field is included. The format string contains the following identifiers to
express how the substring should be interpreted:
%p AM/PM indicator
%#d, %#H, %#I, %#m, %#M, %#S, %#y, %#Y Same as above but with no leading zeros
DataLimit : The absolute number of bytes that the user is allowed to use; this includes a group that
specifies the unit in which the value is expressed.
OverDataLimit, Congested : Modifies flags that are reported to apps to indicate that the user
has exceeded their data limit or that the network is under heavy load.
InboundBandwidth, OutboundBandwidth : If a maximum bandwidth is being imposed by the
network, this specifies the groups that represent the value and the units.
PlanType : Specifies how the user is charged for future usage.
Caution Because SMS messages influence Windows behavior, only trusted SMS messages can be consumed.
Security is maintained by restricting the sender address. This security method assumes that your network’s SMS
Gateway ensures that messages from restricted senders cannot be spoofed.
Wi-Fi information
This section lets you provide any number of Wi-Fi network profiles for Windows to use. The format of the
section is similar to the XML schema that is used by the Windows native WLAN API.
NOTE
One profile can contain multiple SSIDs, if all other settings are the same. If different networks vary in other ways
(authentication method, encryption settings, plan, and so on), you must create additional profiles.
When you specify the WLAN section, you must also specify all profiles that should be configured on the
computer. If those profiles reference a data plan, the plans section must also be included. The behavior that
occurs when this section is processed is as follows:
If the computer has a profile that is no longer specified, it is deleted.
If you specify a profile, it is updated or created.
An empty WLAN section deletes all profiles.
Omitting the WLAN section leaves the WLAN profiles on the machine unchanged.
An additional node in this section is the associated plan. This node enables Windows to associate the WLAN
profile with a plan that is described in the plans section. The plan lets you inform Windows of the metering state
of the network and influence the behavior of Windows during the time that the computer is connected to the
network.
Unencrypted network, no automatic authentication
This profile configures Windows to connect to an open network.
If this network contains a captive portal, the browser is opened upon connection to the network.
If the network does not contain a captive portal, the user is connected with no further action.
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>Contoso Wi-Fi</name>
<SSIDConfig>
<SSID>
<name>Contoso Wi-Fi</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
</security>
</MSM>
</WLANProfile>
Plan information
Each mobile broadband and hotspot profile references a plan. Multiple profiles can reference the same plan.
Plans are described in a separate top-level section.
The Plan is divided into two sections—Description and Usage. This allows you to initially provide profiles and
descriptions in a larger provisioning file, and then subsequently provide smaller provisioning files that contain
only the customer’s current usage.
This information is used to directly affect the behavior of Windows, and is provided to applications to tailor their
behavior to the network. This information can be made available to third-party applications through network
information APIs.
Description
The elements that generally change with low frequency over a customer’s subscription period, including:
PlanType The type of billing relationship the customer has with the operator:
Unrestricted Usage does not incur additional cost.
Fixed The user is allotted a certain amount of usage for a fixed cost.
Variable The user pays based on usage.
SecurityUpdatesExempt A Boolean value that specifies whether security updates count toward the
customer’s usage.
DataLimitInMegabytes The user’s allotted usage, if PlanType is Fixed .
BillingCycle Defines the plan's starting date and time, its duration, and what happens at the end of the
billing cycle.
BandwidthInKbps The user’s connection speed as allowed by the network; this can reflect the norm for
their plan, or reflect a lower rate that is currently imposed by the carrier due to congestion or excessive
use (maximum of 2 Gbps).
MaxTransferSizeInMegabytes An integer that expresses the size of an individual download that a
compliant application should permit over a metered connection, without explicit user approval of the
connection being used.
UserSMSEnabled Indicates whether the plan includes user-to-user SMS support. If true, Windows will
keep the device attached to the network in Connected Standby even when the mobile broadband
interface is not being used. If false, Windows can power down the mobile broadband interface to
conserve power, thereby resulting in the device not being addressable by the network when the
computer is idle.
Usage
The following elements can change with higher frequency:
UsageInMegabytes The user’s most recent data usage.
OverDataLimit A Boolean value that indicates whether the user has passed the allotted usage, if
PlanType is Fixed .
Congested A Boolean value that indicates whether a lower connection speed than usual is being
imposed due to excessive usage. The Congested flag indicates that the network is currently experiencing
(or expects to experience) heavy load, and lower-priority transfers should be deferred until another time,
if possible. You can use this flag to indicate concepts such as peak hours, or to respond to an overloaded
hotspot.
Refresh
You can push updated settings to the computer as required because of network changes or for technical
support. Windows attempts periodic refreshes by using information that is provided by you or by the
provisioning API. A refresh can be triggered by SMS notifications from the operator. To enable Refresh, you must
provide the following information in the provisioning XML:
TrustedCer tificates A list of certificate thumbprints that have trusted signatures on future provisioning
files.
DelayInDays The (integer) number of days before which a refresh is not attempted.
RefreshURL The HTTPS URL to get the latest copy of the user’s provisioning file.
UserName & Password Optional credentials that are to be presented by using HTTP-Auth when
retrieving the re-provisioning file. This information must be encrypted when stored.
Alternatively, the mobile broadband app can provide a new provisioning file at any time, based on
communication between the app and the operator’s backend.
<RefreshParameters>
<DelayInDays>30</DelayInDays>
<RefreshURL>https://www.contoso.com/refresh</RefreshURL>
<Username>[PLACEHOLDER]</Username>
<Password>[PLACEHOLDER]</Password>
</RefreshParameters>
Signature
Because provisioning modifies system settings that persist after the user has exited or uninstalled the app, a
stricter measure of verification is required than for most APIs. This verification is provided by a combination of
operator-specific hardware (the SIM), cryptographic signatures, and user confirmation.
Provisioning requirements:
USER C O N F IRM AT IO N
SIM P RESEN T ? SO URC E O F P RO VISIO N IN G SIGN AT URE REQ UIREM EN T REQ UIREM EN T
No, Wi-Fi provider Mobile broadband appor Certificate must: User is prompted to
web site - Chain back to trusted root confirm the first time the
CA. certificate is used; no
- Be marked for Extended confirmation is required
Validation. thereafter.
Permitted combinations
Although Global is the only first-level node that is required by the schema, certain combinations of other nodes
are typical. This section discusses these typical combinations:
Profiles (WL ANProfiles, MBNProfiles) + Plans including Description and Usage Creates or
updates the full set of profiles, and applies plan information and current usage to each. An error is
returned if a profile references a Plan that is not specified in the same provisioning file, and a warning is
returned if no profile in the provisioning file references a specified Plan.
Plans including Description and (optionally) Usage Updates Plan information for existing profiles
on the computer, but does not modify the profiles on the computer. A warning is returned if no profile on
the computer references a specified Plan.
Plans including Usage only Updates usage information in existing profiles on the computer, but does
not modify the profiles or the description of the Plan that is associated with each profile.
Common Scenarios
Here are some common scenarios that you may need as you create provisioning metadata:
Find the account provisioning schema
Apply provisioning XML to the device
Provision the device to connect automatically to a mobile broadband network
Provision the device to connect automatically to a Wi-Fi network
Provision the device to connect automatically to a WISPr-enabled hotspot
Sending activation to the mobile broadband device
Force the mobile broadband device to reconnect to the network after provisioning completes
Updating data usage statistics for a connection profile
Update data usage by using an SMS message
Find the account provisioning schema
XSD schemas are available under %SYSTEMROOT%\schemas\provisioning on any computer that is
running Windows 8, Windows 8.1, or Windows 10.
Apply provisioning XML to the device
You can apply a provisioning XML file to a device by using a mobile broadband app, a UWP app, or from a web
site.
To provision from a mobile broadband app:
1. Instantiate a ProvisioningAgent instance (by using
Windows.Networking.NetworkOperators.ProvisioningAgent.CreateFromNetworkAccountId ).
2. Call ProvisionFromXmlDocumentAsync , passing in the unsigned provisioning XML document.
The asynchronous operation complete and the results of the provisioning operation are returned.
To provision from a UWP app other than the mobile broadband app:
1. Generate a signed Account Provisioning XML document.
2. Instantiate a ProvisioningAgent instance (by using the default constructor).
3. Call ProvisionFromXmlDocumentAsync , passing in the signed XML document.
The asynchronous operation completes and the results of the provisioning operation are returned.
From a web site:
1. Generate a signed Account Provisioning XML document.
2. Call window.external.msProvisionNetworks , passing in the signed XML document.
The operation completes and the results of the provisioning operation are returned.
Provision the device to connect automatically to a mobile broadband network
You can define a provisioning XML document by using an MBNProfile section.
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{00000000-1111-2222-3333-444444444444}</CarrierId>
<SubscriberId>1234567890</SubscriberId>
</Global>
<MBNProfiles>
<DefaultProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<Name>Profile Name</Name>
<Description>The Description</Description>
<HomeProviderName>Contoso</HomeProviderName>
<Context>
<AccessString>apn</AccessString>
<UserLogonCred>
<UserName>username</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
</CarrierProvisioning>
NOTE
The child elements of DefaultProfile are required. See the provisioning XML schema reference for more details.
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{00000000-1111-2222-3333-444444444444}</CarrierId>
<SubscriberId>1234567890</SubscriberId>
</Global>
<WLANProfiles>
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>My Wi-Fi Hotspot</name>
<SSIDConfig>
<SSID>
<name>wifihotspot1</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
</CarrierProvisioning>
The child elements of MSM define how to connect to the network. This includes any necessary EAP
configuration. All child elements of the MSM element in the WLAN_profile Schema are supported. See the
provisioning XML schema reference for more details.
Provision the device to connect automatically to a WISPr-enabled hotspot
You can use either of the following two ways to enable hotspot authentication:
1. Directly declare credentials by using the BasicAuth directive:
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<WLANProfiles>
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>Contoso Wi-Fi</name>
<SSIDConfig>
<SSID>
<name>Contoso Wi-Fi</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
<HotspotProfile xmlns="http://www.microsoft.com/networking/WLAN/HotspotProfile/v1">
<BasicAuth>
<UserName>[PLACEHOLDER]</UserName>
<Password>[PLACEHOLDER]</Password>
</BasicAuth>
<TrustedDomains>
<TrustedDomain>hotspot.contoso.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
</CarrierProvisioning>
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<WLANProfiles>
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>Contoso Wi-Fi</name>
<SSIDConfig>
<SSID>
<name>Contoso Wi-Fi</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
<HotspotProfile xmlns="http://www.microsoft.com/networking/WLAN/HotspotProfile/v1">
<ExtAuth>
<ExtensionId>Alice</ExtensionId>
</ExtAuth>
<TrustedDomains>
<TrustedDomain>hotspot.contoso.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
</CarrierProvisioning>
You should directly define credentials when possible. Redirecting to another app has power and complexity
implications.
Sending activation to the mobile broadband device
An arbitrary binary large object (BLOB) that is contained inside the CarrierSpecificData element can be
Base64-encoded and sent to the device by using the ProvisioningAgent. You can do this by using the
Activation<Ser viceActivatation> directive in the provisioning XML:
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{00000000-1111-2222-3333-444444444444}</CarrierId>
<SubscriberId>1234567890</SubscriberId>
</Global>
<Activation>
<ServiceActivation xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<CarrierSpecificData>YXJiaXRyYXJ5ZGF0YQ==</CarrierSpecificData>
</ServiceActivation>
</Activation>
</CarrierProvisioning>
NOTE
If the radio is successfully cycled on in a ReregisterToNetwork but the automatic connection back to the network using
the default profile fails, then subsequent retries do not cycle the radio again.
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{00000000-1111-2222-3333-444444444444}</CarrierId>
<SubscriberId>1234567890</SubscriberId>
</Global>
<Activation>
<!-- Cycle the radio and reconnect to the default profile with an
initial execution delay of 30 seconds and retries every 1 minute
up to 3 times.
-->
<ReregisterToNetwork
xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1"
Delay="PT30S"
RetryCount="3"
RetryInterval="PT1M"
/>
</Activation>
</CarrierProvisioning>
Troubleshooting
If you run into provisioning problems, you can use the following sections to help you figure it out.
Provisioning API results
If provisioning fails, you will receive an exception when you try to perform the provisioning action. Failures that
can cause exceptions include the following:
The provisioning XML does not conform to the CarrierControlSchema schema.
The provisioning XML requires a signature, but is not appropriately signed.
Partial provisioning failures
Portions of the provisioning operation might not succeed because of a variety of reasons. For example, you
might have a reference to Wi-Fi hardware that is not present at the time of provisioning. The provisioning agent
does a best effort attempt to provision everything in the file. When something fails, it is noted in the
provisioning results that are asynchronously returned by using ProvisionFromXmlDocumentAsync .
The results are returned as XML and can be parsed to discover the failure. Elements provide structure to show
what failed, and ErrorCode attributes indicate the reason for the failure as a standard HRESULT.
For example, the following error code indicates that no WLAN profiles were provisioned because the WLAN
service was not active:
<CarrierProvisioningResult>
<WLANProfiles ErrorCode=”80070426”/>
</CarrierProvisioningResult>
<CarrierProvisioningResult>
<WLANProfiles>
<WLANProfile Name=”MyProfile” ErrorCode=”80070005”/>
</WLANProfiles>
</CarrierProvisioningResult>
Event Logs
Events in the Applications and Ser vices Logs\Microsoft\Windows\NetworkProvisioning\Operational
channel can provide detailed feedback about provisioning failures.
PowerShell ProvisioningTestHelper module
You can import the ProvisioningTestHelper module from the Windows 8, Windows 8.1, and Windows 10
SDKs. By using this module, you can generate and install EV certificates, sign an XML file by using the installed
certificate, and validate the XML against the provisioning schema. To import the module into a PowerShell
session, type the following command:
Import-Module "<path_to_sdk>\bin\<arch>\ProvisioningTestHelper.psd1"
Where <path_to_sdk\bin\<arch>> is the install location of the Windows 8, Windows 8.1, or Windows 10 SDK
that corresponds to the architecture of the computer.
After you import this module, the following four PowerShell cmdlets are available:
Install-TestEVCer t Generates a new CA certificate, registers it on your test computer as a trusted EV SSL
provider, and uses it to generate and install an EV certificate for use in signing. You must run this cmdlet
only one time to install the certificates. You can sign any number of files by using the certificates.
The client certificate has the name that is specified in the command and the root certificate has “Root”
appended to it together with the client certificate name. The -CertName parameter is optional. If the –
CertName parameter is not specified, MBAPTestCer t is used.
The -RootCertOutputPath parameter is also optional. It should be used if you want to export the root
certificate to be installed on another computer by using the Install-RootCertFromFile cmdlet.
Install-RootCer tFromFile Applies the test root certificate on a different computer, to test the client
experience on a computer other than the development computer.
Install-RootCertFromFile -CertFile <complete path to the root certificate>
Conver tTo-SignedXml Uses an EV certificate (generated for test, or issued by a third-party provider) to
apply an XML-DSig signature to a provisioning XML file. This signature from a trusted certificate causes
Windows to accept the provisioning file as valid from a mobile broadband app with no affiliated
hardware.
ConvertTo-SignedXml -InputFile <complete path to the input XML file> -OutputFile <complete path to
the output XML file> -CertName <name of the certificate used to sign the xml>
This command will sign the input XML file, put the signature in the XML, and save it to the output XML
file.
Test-ValidProvisioningXml Validates the Provisioning XML (signed or unsigned) against the
provisioning schema.
This section contains information about both COSA and apndatabase.xml (APN database). COSA is a newer
format used in Windows 10, version 1703 and later, while APN database is used for Windows 8, Windows 8.1,
and versions of Windows 10 before Windows 10, version 1703.
COSA and the APN database are used by Windows networking components, such as the Windows Connection
Manager, to provide a seamless connection experience for end users by supplying and trying available
connection APNs based on the user’s mobile broadband device. COSA and the APN database contain the
information needed to connect to the mobile broadband network, allowing Windows to connect automatically
with minimal user input. They maintain access strings for different mobile network operators, enabling a user’s
connection to the operator’s network prior to acquiring any additional software or metadata. For example, a
user can get connected without having a mobile broadband app installed.
In addition to provisioning information, COSA and APN database also include a URL to the account experience
website. After automatically connecting to the operator’s network, the account experience website opens in the
default browser, where the user can purchase a subscription or one-time access.
The following topics present further information about APNs, COSA, and APN database.
APN schema definition
APN elements
COSA overview
APN database overview
COSA/APN database submission
APN schema definition
4/13/2022 • 2 minutes to read • Edit Online
NOTE
The XML document must be saved by using UTF-8 encoding.
This section describes the XML elements defined by the APN XML schema. The following is a list of these
elements in the order in which they are defined in the XML schema.
OperatorList
Operator
HardwareIdList
HardwareId
ConnectionInfoList
ConnectionInfo
TrustedCertificateList
TrustedCertificate
OperatorList
4/13/2022 • 2 minutes to read • Edit Online
The OperatorList element specifies a list of operators included in the APN database.
Usage
<OperatorList>
child elements
</OperatorList>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
There are no parent elements.
XSD
<xs:element name="OperatorList">
<xs:complexType>
<xs:sequence>
<xs:element ref="Operator" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The OperatorList element is required.
Operator
4/13/2022 • 2 minutes to read • Edit Online
The Operator element specifies the details of an operator that is included in the APN database.
Usage
<Operator name=”xs:string” AccountExperienceURL=”xs:anyURI” OperatorGUID=”GUID”>
child elements
</Operator>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Operator">
<xs:complexType>
<xs:sequence>
<xs:element ref="HardwareIdList"/>
<xs:element ref="ConnectionInfoList"/>
<xs:element ref="TrustedCertificateList" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="AccountExperienceURL" type="xs:anyURI" use="optional"/>
<xs:attribute name="OperatorGUID" type="GUID" use="optional"/>
</xs:complexType>
</xs:element>
Remarks
The Operator element is required.
HardwareIdList (APN element)
4/13/2022 • 2 minutes to read • Edit Online
The HardwareIdList element specifies a list of hardware IDs for the operator.
Usage
<HardwareIdList>
child elements
</Operator>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="HardwareIdList">
<xs:complexType>
<xs:sequence>
<xs:element ref="HardwareId" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The HardwareIdList element is required.
HardwareId (APN element)
4/13/2022 • 2 minutes to read • Edit Online
The HardwareId element specifies the HWID for the specified operator.
Usage
<HardwareId>
...insert text here
</HardwareId>
Attributes
There are no attributes.
Text value
A string that represents an encoded hardware ID. Generating the proper hardware ID values involves a complex
algorithm. We recommend that you use mbidgenerator.exe to generate your hardware IDs.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element ref="HardwareId" maxOccurs="unbounded"/>
<xs:element name="HardwareId">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Remarks
The HardwareId element must represent one of the following:
GSM networks: IMSI range
GSM networks: ICCID range
CDMA networks: Provider name value
CDMA networks: Provider ID value (also known as SID)
The HardwareId element is required.
ConnectionInfoList
4/13/2022 • 2 minutes to read • Edit Online
The ConnectionInfoList element specifies a list of connections for the specified operator.
Usage
<ConnectionInfoList>
child elements
</ConnectionInfoList>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element ref="ConnectionInfoList"/>
<xs:element name="ConnectionInfoList">
<xs:complexType>
<xs:sequence>
<xs:element ref="ConnectionInfo" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The ConnectionInfoList element is required.
ConnectionInfo
4/13/2022 • 2 minutes to read • Edit Online
The ConnectionInfo element specifies a list of connections for the specified operator.
Usage
<ConnectionInfoList AccessString=”xs:string” Username=”xs:string” Password=”xs:string”
FriendlyName=”xs:string” Purchase=”xs:Boolean” Internet=”xs:Boolean” AutoConnectOrder=”xs:positiveinteger”
Compression=”xs:token” AutoProtocol=”xs:token”>
</ConnectionInfoList>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element ref="ConnectionInfo" maxOccurs="unbounded"/>
<xs:element name="ConnectionInfo">
<xs:complexType>
<xs:attribute name="AccessString" use="optional">
<!--The AccessString element identifies the APN or dial string to be used to establish a data
connection -->
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="0"/>
<xs:maxLength value="100"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Username" use="optional">
<!--The UserName element specifies the user name for logon -->
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="0"/>
<xs:maxLength value="255"/>
<xs:whiteSpace value="collapse"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Password" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="0"/>
<xs:maxLength value="255"/>
<xs:whiteSpace value="collapse"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="FriendlyName" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="0"/>
<xs:maxLength value="255"/>
<xs:whiteSpace value="collapse"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Purchase" type="xs:boolean" use="required"/>
<xs:attribute name="Internet" type="xs:boolean" use="required"/>
<xs:attribute name="AutoConnectOrder" type="xs:positiveInteger" use="optional"/>
<xs:attribute name="Compression" use="optional">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="DISABLE"/>
<xs:enumeration value="ENABLE"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="AuthProtocol" use="optional">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="NONE"/>
<xs:enumeration value="PAP"/>
<xs:enumeration value="CHAP"/>
<xs:enumeration value="MsCHAPv2"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
Remarks
The ConnectionInfo element is required.
TrustedCertificateList
4/13/2022 • 2 minutes to read • Edit Online
The TrustedCertificateList element specifies a list of trusted certificates for the operator.
Usage
<TrustedCertificateList>
child elements
</TrustedCertificateList>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element ref="TrustedCertificateList" minOccurs="0"/>
<xs:element name="TrustedCertificateList">
<xs:complexType>
<xs:sequence>
<xs:element ref="TrustedCertificate" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The TrustedCertificateList element is optional.
TrustedCertificate (APN element)
4/13/2022 • 2 minutes to read • Edit Online
The TrustedCertificate element specifies a trusted certificate for the specified operator.
Usage
<TrustedCertificate SubjectName=”xs:string” IssuerName=”xs:string”>
</TrustedCertificate>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element ref="TrustedCertificate" maxOccurs="unbounded"/>
<xs:element name="TrustedCertificate">
<xs:complexType>
<xs:attribute name="SubjectName" type="xs:string" use="required"/>
<xs:attribute name="IssuerName" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Remarks
The TrustedCertificate element is optional.
APN example
4/13/2022 • 2 minutes to read • Edit Online
The following XML document uses the APN XML schema to specify the APN information for a service:
COSA, or Country and Operator Settings Asset, is the new format that Mobile Operators (MOs) use in Windows
10, version 1703 and later to provision Windows devices for mobile broadband. The existing APN database
(apndatabase.xml) from Windows 8, Windows 8.1, and versions of Windows 10 before 1703 has been
converted to COSA, which is ingestible by the new provisioning framework. Note that these previous versions
of Windows will continue to use the older APN database for provisioning desktop devices.
For more information about the older APN database, see APN database overview.
To see a list of available settings MOs can configure in desktop COSA, see Desktop COSA/APN database
settings.
FAQ
What are the settings that MOs can specify in COSA?
What events trigger the application of new MO settings?
What SIM information from modems does COSA use?
Is there an algorithm to make the best APN match?
Where is the COSA database stored, and can it be visually inspected like apndatabase.xml?
What happens when a device updates from Windows 10, version 1607 (or earlier) to Windows 10, version
1703? Are custom or manually created APNs migrated? Do they still have priority over the defaults from the
database?
Why does the Set as metered connection setting sometimes change from Off to On ?
What are the settings that MOs can specify in COSA?
The settings are largely the same as what MOs configured in apndatabase.xml, with a few exceptions and new
additions. For details, see the tables in Planning your desktop COSA/APN database submission.
What events trigger the application of new MO settings?
Three events trigger the Windows provisioning engine to look for a change in settings:
1. The insertion or removal of a physical SIM (change in ICCID)
2. Reconfiguration of an eSIM (change in ICCID)
3. When the device boots
What SIM information from modems does COSA use?
For MO/MVNO discovery, Windows tries to make the best match for an available profile in the COSA database
using SPN from the SIM in the modem.
Is there an algorithm to make the best APN match?
In versions of Windows before Windows 10, version 1703, MOs could specify an auto-connect order. Windows
10, version 1703 and later continue to use a round-robin approach through all available APNs, but there is no
longer a specific order that the algorithm uses.
Where is the COSA database stored, and can it be visually inspected like apndatabase.xml?
COSA is in the format of a Windows 10 provisioning package (.ppkg). It is in the
Windows\Provisioning\COSA\Microsoft folder. You can use a third-party tool, such as 7-Zip File Manager
(www.7-Zip.org), to visually inspect its contents.
Note that OEM extensions to COSA, if specified in the device image, are in the COSA\OEM folder. For more
information, see Customize the Country and Operator Settings Asset.
What happens when a device updates from Windows 10, version 1607 or earlier to Windows 10, version 1703
or later? Are custom or manually created APNs migrated? Do they still have priority over the defaults from
the database?
COSA replaces apndatabase.xml after the upgrade. If an APN was provisioned in the previous version, whether
custom, manual, or device-provisioned via the database, it is migrated as a part of the upgrade to version 1703
and the device continues to use it for connectivity without requiring any additional action. Manually provisioned
APNs still have priority over the defaults from the database just as they did in version 1607 and earlier.
Why does the "Set as metered connection" setting sometimes change from Off to On?
Updates to the Windows operating system may include updates for the COSA database. If the database is
updated, the provisioning engine may remove the cellular profiles. When the system restarts after database
updates are installed, the provisioning engine reinstalls the cellular profiles. This operation resets user settings
to their default values. For example, Set as metered connection changes from Off to On . This behavior is by
design.
APN database overview
4/13/2022 • 2 minutes to read • Edit Online
The APN database, or apndatabase.xml, is the provisioning database that Mobile Operators (MOs) use to
configure mobile broadband experiences for their networks. It is available in Windows 8, Windows 8.1, and
versions of Windows 10 before Windows 10, version 1703.
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8,
Windows 8.1, and versions of Windows 10 before version 1703 will continue to use the APN database while
Windows 10, version 1703 and later use COSA.
For more info about COSA, see COSA overview.
To see a list of available settings MOs can configure in the APN database, see Desktop COSA/APN database
settings.
IMPORTANT
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8, Windows
8.1, and versions of Windows 10 before version 1703 will continue to use the APN database while Windows 10, version
1703 and later use COSA. For more information about COSA, see COSA overview.
Use the sections in this topic when you are planning to add a new APN to the baseline COSA/APN database that
ships with Windows desktop devices, or update an existing one.
NOTE
Because the previous entries will be deleted, it is important to list all APNs for the Operator and
Countr y/Region combination, including the ones that are not changing.
For example, when the following values are entered in a row in the spreadsheet:
Operator: Contoso
Country/Region: Argentina
All entries currently in the COSA or APN connectivity database that match the following format will be
deleted and replaced with the row in your spreadsheet for that Operator and Countr y/Region
combination:
If the Operator and Countr y/Region entries do not match content that already exists in COSA or the
APN database, a new APN is created.
For example, if the following values are entered in a row in the spreadsheet:
Operator: Contoso
Country/Region: Argentina
If it does not exist in the appropriate connectivity database, a new entry is added after your submission is
accepted that looks like the following:
On each row of the spreadsheet that is submitted, you must specify only one of the following:
An MCC+MNC with a blank IMSI range
An MCC+MNC with a specific IMSI range
An MCC+MNC with a specific ICCID range
An MCC+MNC with a specific GSM provider name
If you have created a website for setting up Mobile Broadband service, it is important to provide the
Account Experience URL and certificate data.
Access strings used for plan purchase (Purchase Flag =Y ) can be one of the following:
For GSM networks, an APN with a specified User Name and Password used for purchasing the
subscription.
For CDMA networks, a Network Access Identifier (NAI) is used for purchasing the subscription.
Access strings used for Internet connectivity (Connect Flag =Y ) can be one of the following:
For GSM networks, an APN with a specified User Name and Password used to connect to the
Internet.
For CDMA networks, a Network Access Identifier (NAI) is used to connect to the Internet.
Once your spreadsheet is complete, you can test the APNs you’ve entered. For the next steps in testing your
APN update, see Testing your desktop COSA/APN database submission.
Desktop COSA/APN database settings
4/13/2022 • 11 minutes to read • Edit Online
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.
CertIssuerName The Cert Issuer Name of Optional If specified, you must also
your signing certificate used specify the Cert Subject
for operator XML Name and Carrier GUID.
provisioning.
CertSubjectName The Cert Subject Name of Optional If specified, you must also
your signing certificate used specify the Cert Issuer
for operator XML Name and Carrier GUID.
provisioning.
Carrier GUID The self-assigned GUID that Optional If specified, you must also
is used in future operator specify the Cert Subject
XML provisioning packages. Name and Cert Issuer
Name.
M IN IM UM
SUP P O RT ED
O P T IO N A L O R W IN DO W S VERSIO N
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES F O R C O SA
Country/Region The country or Required This entry might Windows 10, version
region for the APN change to match 1703
entry. how Windows refers
to a particular
country or region.
M IN IM UM
SUP P O RT ED
O P T IO N A L O R W IN DO W S VERSIO N
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES F O R C O SA
Operator The name of the Required Ensure you use the Windows 10, version
operator. You do not same spelling and 1703
need to include the capitalization each
country or region in time you submit an
this field. update for your APN
entries.
MCC A 3-digit MCC value Optional for ICCID Windows 10, version
used for GSM IMSI ranges. 1703
submissions.
IMSI Range - Start A 15-digit number Optional The number should Windows 10, version
that includes the end in 00. 1703
MCC+MNC at the If this setting and
start of the number. the IMSIRange
- End setting is
left blank but the
MCC and MNC
entries are
specified, the
entire
MCC+MNC
range is covered.
IMSI Range - End A 15-digit number Optional The number should Windows 10, version
that includes the end in 99. 1703
MCC+MNC at the If this setting and
start of the number. the IMSI Range
- Star t setting is
left blank but the
MCC and MNC
entries are
specified, the
entire
MCC+MNC
range is covered.
ICCID Range - Start A 19- or 20-digit Optional The number should Windows 10, version
number that starts end in 00. 1703
with 89 (the ICCID
issuer identifier
number).
ICCID Range - End A 19- or 20-digit Optional The number should Windows 10, version
number that starts end in 99. 1703
with 89 (the ICCID
issuer identifier
number).
M IN IM UM
SUP P O RT ED
O P T IO N A L O R W IN DO W S VERSIO N
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES F O R C O SA
AccountExperienceUR Used by Windows Optional Helps improve the Windows 10, version
L Connection Manager plan acquisition 1703
if the user does not experience.
have an active plan If both AppID
and tries to connect and
to your network. AccountExperienc
eURL are
specified, AppID
receives higher
precedence and
the UX will not
display the
AccountExperienc
eURL.
FriendlyName A name for this APN Optional Appears in the Windows 10, version
entry that is Windows Connection 1703
understandable and Manager in cases
meaningful to where Windows
subscribers. cannot automatically
connect to the
network.
AutoConnectOrder Windows tries Optional If you have more Windows 10, version
connections to the than one access 1809
APNs provided by string for an
the operator and operator, this setting
marked as “auto- must start with 1.
connect” in APN This is needed for
database or COSA Windows to try
until it successfully several APN entries
connects to the that share either an
mobile network. If all IMSI range, ICCID
auto-connect range, CDMA
attempts fail, provider ID, or
Windows will show a CDMA provider
prompt allowing the name when the user
user to pick an APN tries to connect.
or enter a custom
APN.
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
SPN An identifier string Optional Helps to identify the Windows 10, version
for the Service MO/MVNO's 1703
Provider Name (SPN) network. If left blank,
defaults to empty
string and does
nothing.
AlwaysOn Describes whether Required If left blank, defaults Windows 10, version
the connection is to "true." 1703
always on or not.
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
BrandingName The mobile Optional If left blank, defaults Windows 10, version
broadband device to empty string and 1709
typically provides the does nothing.
operator name,
which Windows
shows in the
Windows Connection
Manager. You can
override this name
by specifying a
custom name in
metadata.
BrandingIcon A custom logo that Optional Icons must have Windows 10, version
appears in the transparent 1709
Windows Connection backgrounds and
Manager next to smooth edges. It's
your network entry. 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
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
Roaming Specifies the roaming Optional Possible values: Windows 10, version
conditions under 0: Home 1709
which the connection network only
should be activated. 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).
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
DataMarketplaceRoa This setting controls Optional This setting works Windows 10, version
mingUIEnabled whether the roaming with the 1709
UI should be shown Suppor tDataMark
for a SIM or eSIM etPlace setting. The
that is part of the possible values are:
Mobile Plans service. 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 .
UIOrder The index to control Required if UIName If not specified, Windows 10, version
the UIName value's is specified; Optional defaults to 0 . 1709
dropdown list picker otherwise
position.
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
ESIM_PROV A true/false string Impor tant Optional If left blank, Windows 10, version
describing whether unless the MO defaults to 1709
the profile is to be supports an eSIM "false."
considered as an provisioning profile,
eSIM provisioning in which case it is An eSIM
profile. required. 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.
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
Before submitting an APN update request to Microsoft, it is important for the MNO or MVNO to validate the
APN entries that they are about to submit. Microsoft does not have access to your network, so it is your
responsibility to ensure the values that are being submitted are valid and work correctly.
NOTE
You will need to provide a credit card to open the incident, but you will not be charged.
IMPORTANT
Create a backup of the original provisioning package before performing the following actions. The original provisioning
package is located here: %systemroot%\Provisioning\Cosa\Microsoft\Microsoft.Windows.Cosa.Desktop.Client.ppkg .
1. Remove any SIM from the device, if any.
2. Copy the script and the new PPKG file to a local directory.
3. Open an elevated Command Prompt window and change to the directory containing the script.
4. Run the script with this syntax to apply the PPKG:
ApplyCosaProvisioning.BAT -a <full path to the PPKG local directory> .
a. For example:
ApplyCosaProvisioning.BAT -a "C:\FromMicrosoft\Microsoft.Windows.Cosa.Desktop.Client.ppkg"
5. Insert the SIM and await provisioning.
Restore the original PPKG file
WARNING
Once validation of the new PPKG received from Microsoft has completed, always restore it with the following steps.
Restoring back to the original PPKG will ensure that you receive the latest COSA updates via Windows Update.
NOTE
This test does not simulate the full experience, which is described in the Modify the local APN database section.
1. Insert a SIM into the PC that works with the APN value you want to test.
2. Turn on the PC, log on to Windows, and open Windows Connection Manager. The mobile broadband
connection should appear.
3. Right-click the mobile broadband connection, and then select View connection proper ties .
4. Enter the APN value to test into this dialog box.
5. Save your changes, and then try to connect to the mobile broadband network.
Modify the local APN database
Before you submit an APN update, you should editing the local APN database or creating a new one for testing.
By doing this, you closely simulate the full experience because the APN selection logic that Windows Connection
Manager uses is fully tested.
Modify the local APN connectivity database
1. Copy any existing values from the local APN database file -- View the existing entries in the local
APN database on your PC and copy these entries into a new XML file. If you don’t have any APN entries in
the local copy of the APN database, skip this step and start with a blank XML file.
2. Modify values in the XML file according to the published APN schema – Ensure that your APN
entries follow the APN database schema reference.
3. Generate your hardware IDs – Hardware IDs specify one or more hardware identification strings that
match the SIM characteristics to an APN entry in the database. Each string is specified by a HardwareId
element. We recommend that you use mbidgenerator.exe to generate your hardware IDs. For more
information, see Using mbidgenerator.exe to generate hardware IDs.
4. Validate that the file you generated conforms to the published APN database schema --
Always perform a schema check to ensure that the file you have generated conforms to the APN
database schema reference.
5. Over write the APN connectivity database on the PC with your new database
a. From an elevated command prompt, type cd %systemroot%\system32 and then press ENTER.
b. Type takeown /f .\ApnDatabase.xml and then press ENTER.
c. Type icacls .\ApnDatabase.xml /grant %username%:F and then press ENTER.
d. Copy your customized version of the ApnDatabase.xml file to the directory.
6. Validate that the APN entries exist in the local APN database:
a. Ensure that there are no existing mobile broadband profiles by running the following command:
netsh mb show profiles
b. If a mobile broadband profile exists, type netsh mb profile interface=<Interface name>
name=<Profile name>
c. Ensure that the device doesn’t have a provisioned context by running the following command:
netsh mb show provisionedcontext interface=<Interface name>
Note If the device provides a provisioned context, Windows will use the APN from that
provisioned context instead of the local APN database and you will not able to test your APNs. If
the device has a provisioned context, you need to acquire another device that doesn’t provide a
provisioned context.
d. Open Windows Connection Manager. It will show the Wi-Fi and mobile broadband networks that
are within range.
e. Select the Mobile Network, and then click Connect .
f. If you have multiple APNs that match the SIM properties, Windows Connection Manager will try
each of the matching APNs until a successful connection takes place. If none of the APNs connect,
Windows Connection Manager will either show an error or show a custom APN entry screen,
allowing the user to enter a custom APN.
Note The auto-connect order that you specify in the APN database is used to determine the order
in which APNs are tried.
g. If you have only one APN in the APN database, Windows will automatically connect to the
operator network.
NOTE
You can see which APN was applied to the connection profile by opening Windows Connection Manager, right-clicking the
Mobile Broadband entry for your network, and then clicking Proper ties .
Submitting the desktop COSA/APN database
update
4/13/2022 • 4 minutes to read • Edit Online
IMPORTANT
The following steps to submit an APN update apply to both desktop COSA, which is used for Windows 10, version 1703
and later, and apndatabase.xml, which is used for Windows 8, Windows 8.1, and versions of Windows 10 before 1703.
Microsoft will convert apndatabase.xml submissions to COSA if you are targeting Windows 10, version 1703 or later.
Now that you’ve tested the APN entries, it’s now time to submit them to Microsoft by following the steps in this
topic.
Please describe what testing you have done on the APNs that you are submitting.
[describe here]
Have you tested these APN values on your network? Windows cannot test these APNs for you because we do not
have access to your wireless network.
[yes/no]
Do you understand that all the APNs that match the Operator and Country/Region combination will be wiped out
and replaced by the APNs that you have attached to this request?
[yes/no]
Do you certify that you are entitled to submit an update on behalf of this operator?
[yes/no]
IMPORTANT
If you do not sign-off within the allotted time period, your changes will be reverted from the next released update of the
APN connectivity database. You’ll need to resubmit your APN submission and wait until the next scheduled update.
NOTE
Deletions take place based on Operator and Countr y/Region combination.
Please describe which operator and region combination you wish to have removed from the APN database.
[Describe here. For example: <Operator name="Contoso (Argentina)">]
Do you understand that all the APNs that match the Operator and Country/Region combination will be wiped
out?
[yes/no]
If you wish to add values to the APN database in addition to this deletion request, have you attached an
Excel sheet and questionnaire for that add request?
[not applicable/yes/no]
Do you certify that you are entitled to submit an update on behalf of this operator?
[yes/no]
You can create and submit a service metadata package to create an experience that is deeply integrated with
Windows. When Windows detects mobile broadband hardware that matches the operator’s service metadata
package, it automatically downloads the service metadata and the specified mobile broadband app.
Service metadata contains the information that describes a service, including the following:
The service provider name
One or more service categories
Mobile broadband-specific information
Mobile broadband app
Mobile broadband profiles
Trusted certificates for provisioning XML
DeviceNotificationHandler element
PrivilegedApplications element
The information in the metadata is used to customize aspects of the Windows 8, Windows 8.1, and Windows 10
user experience and provide integration with a mobile broadband app, previously known as a mobile operator
app.
A service metadata package consists of multiple XML documents stored within a .devicemetadata-ms file. Each
document specifies various components of the service’s attributes. These XML documents provide Windows
Connection Manager with customizations that appear to the user, as well as network configuration information.
For reference information about the XML documents in a service metadata package, see Service metadata
package schema reference.
IMPORTANT
In Windows 10, version 1709 and later, this field has been replaced by branding through COSA. Fields in COSA for
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions
of Windows before Windows 10, version 1709, you will still create a metadata package as described in this section.
For more information about COSA, see COSA overview.
This topic provides info on how you can match service metadata to a mobile network operator (MNO) or mobile
virtual network operator (MVNO) so that a mobile broadband app is automatically downloaded when the
mobile broadband device is inserted.
To successfully match service metadata, Windows reads information from the SIM card that is inserted into the
computer. For CDMA networks, the mobile broadband device itself is read. Windows then queries the Windows
Metadata and Internet Services (WMIS) database to download the correct service metadata package. After the
service metadata package is downloaded, Windows downloads the associated mobile broadband app to the
computer.
Use the link from the following list that is appropriate for your network:
Matching on GSM networks
Matching on CDMA networks
For info about the hardware that is required to properly match service metadata to an MNO and MVNO, see
Mobile operator hardware overview.
For info on service metadata, see Service metadata.
For info on the service metadata package schema, see Service metadata package schema reference.
Figure 3 Using ICCID to define MVNOs and an all-encompassing IMSI range for the MNO
Computer #1’s matching request does not match any ICCID values and lands inside the IMSI range that is
defined by the MNO. The MNO service metadata is downloaded on that computer.
Computer #2’s matching request in included in the ICCID range for MVNO B. MVNO B’s service metadata
is downloaded to that computer.
Computer #3’s matching request is included in the ICCID range for MVNO A. MVNO A’s service metadata
is downloaded to that computer.
Computer #4’s matching request does not match any ICCID values and lands inside the IMSI range that is
defined by the MNO. The MNO service metadata is downloaded on that computer.
Option 4: Segmenting ICCID and IMSI ranges
You can use a mixture of ICCID ranges and IMSI ranges to describe the MNO and MVNO networks.
Note ICCID ranges get first priority for matching.
This is the most complex matching model. To ensure proper matching, the MNO and MVNO must frequently
update their service metadata packages.
Figure 4 Segmenting ICCID and IMSI ranges shows an example of client device that request service metadata
from WMIS, and how each matching request from the client is matched to an experience.
This guide walks you through the process of creating a service metadata package on the Windows Dev Center
hardware dashboard, previously known as Sysdev. Service metadata is required to connect a mobile broadband
app to your hardware device. When a user plugs a mobile broadband device into their computer, the associated
service metadata is downloaded and then the mobile broadband app is automatically downloaded.
You can leverage service metadata to create a deeply integrated experience with Windows. Service metadata
packages allow you to include branding information, such as icons and your operator name, configure settings
and permissions for accessing SIM hardware and personal hotspots, and provision mobile broadband apps to
work with your mobile broadband device.
Note
Even though the mobile broadband app is automatically installed, the user must pin it to the Start Screen
manually.
Getting started
To create a successful service metadata package, you must complete the steps included in this section.
Register your company with the Windows Dev Center hardware dashboard
Your company has an active account on the Windows Dev Center hardware dashboard. If your company
does not have an account on the Windows Dev Center hardware dashboard, you can create a new
account and add your user account to you company. For more info, see Administration in the Windows
Dev Center hardware dashboard help.
Your company has a VeriSign code signing certificate to sign the packages.
Service Metadata wizard access and service identifiers registration
MNOs and MVNOs must complete the following steps before you can create a service metadata package:
Request access to the Service Metadata wizard
Register your service identifiers
To complete the steps above, you must send an email to sysdev@microsoft.com with the following info:
The organization name used when you registered for the Windows Dev Center hardware dashboard.
Whether you are a mobile network operator or a mobile virtual network operator.
Your website and justification on why you need to create a service metadata package.
Include the following service identifiers as applicable:
List of GSM Provider IDs
List of GSM Provider Names
List of CDMA SIDs
List of CDMA Provider Names
You should receive an acknowledgement emails with 24 hours that your request was received. However, it could
take up to 5 business days to process the request. If we have conflicts, we’ll send you an email asking for
additional information.
Mobile broadband app
Before you create your service metadata package, ensure that your mobile broadband app has been developed
and associated with the Microsoft Store. This app should provide key experiences, such as plan purchase, data
usage, help and support, as well as highlighting value-added services from the operator. For more info about
creating the mobile broadband app, see the following links:
Mobile broadband WinRT API overview
Mobile operator hardware overview
UWP mobile broadband apps
Note
The mobile broadband app doesn’t have to be published to the Microsoft Store until the service metadata has
been tested and is ready to be published externally. We recommend that the app is published to the Microsoft
Store only after the service metadata package passes preview mode testing.
You can also complete this without using Visual Studio 2013 by doing the following steps:
To gather mobile broadband app information without using Visual Studio 2013
1. Navigate to the package.appxmanifest file for your mobile broadband app.
2. Right-click the file, and then click Open with .
3. Clear the Use this app for all .appxmanifest files check box, click More options , and then click
Notepad .
4. Gather the following attributes from the package.appxmanifest file:
From the Identity element, the Name attribute will be used for the Package name field in the
Service Metadata Wizard.
From Identity element, the Publisher attribute will be used for the Publisher field in the Service
Metadata Wizard.
From the Applications element, the Id attribute from the Application child element will be used
for the App ID field in the Service Metadata Wizard.
5. Save and close the package.appxmanifest file.
2-Create the service metadata package
Service metadata is created by using the Service Metadata Wizard in the Windows Dev Center hardware
dashboard.
To create a ser vice metadata package
1. Navigate to sysdev.microsoft.com.
2. Under the Device metadata heading, click Create mobile broadband experience .
3. On the Ser vice info page, complete the following fields, and then click Next .
Enter the name for your network that is to be used in the Windows network selection
UI – The name of you network that will be displayed to customers in Windows Connection
Manager.
Enter your ser vice number – A GUID that must match the carrier ID field in your provisioning
metadata. You can create a GUID by using Visual Studio 2013. For more information on how to
create a GUID, see Create GUID (guidgen.exe).
Upload your icon that is to be shown in the Windows network selection UI – Click
Browse , and then select the icon that is shown to customers in Windows Connection Manager.
Enter the Windows notification event handler in your app (optional unless entitlement
check is required below) – This is the notification handler that was registered in your mobile
broadband app.
Do you want to allow users to share their mobile broadband connection (personal
hotspot)? – The possible options are Always allow , Allow only with entitlement check
(Windows notification event handler required) , and Never allow . The default option is to
always allow.
Do you want to require system admin privileges to perform PIN unlock on SIMs? – If
you want to require system administrator privileges to PIN unlock a SIM card, click the Yes option.
4. On the Hardware info page, select the information that should be used to identify your experience.
Once a check box is selected, you can add the appropriate network ranges. The ID generated should exist
in the Windows APN database so the right subscriber is identified. For more information about the APN
database, see COSA/APN database submission.
If you are a GSM Provider that uses the International Mobile Subscriber Identity (IMSI), select the
IMSI check box under the GSM heading. In the Provider ID box, enter the GSM service provider
ID. Under the IMSI/ICCID Ranges heading, enter the range, and then click Add .
If you are a GSM provider that uses the integrated circuit card identifier (ICCID), select the SIM ICC
ID check box under the GSM heading. Under the Enter the Provider ID and ICC ID range
heading, enter the range, and then click Add .
If you are a GSM provider that uses the home provider name, select the Home provider name
check box under the GSM heading. Under the Enter the Home Provider Name or enter the
Provider ID (MCC+MNC) heading, enter the provider ID and provider name, and then click Add .
If you are a CDMA provider that uses the SID, select the SID check box under the CDMA heading.
In the Enter the SID box, enter the CDMA SID.
If you are a CDMA provider that uses the provider name, select the Provider name check box
under the CDMA heading. In the Enter Provider Name box, enter the CDMA service provider
name.
Click Next .
5. On the App info page, enter the information you gathered in Step 1 of this topic. If you want to add
additional privileged apps, click Add , and then enter up to 7 more. When all of the privileged apps are
entered, click Next .
6. On the Confirm page, verify that the information is correct. Select the Developer Mode or Preview
Mode option, and then click Submit .
Developer Mode – The package is not signed and it must be manually downloaded and installed
on every computer. Use this option if you want to save the package for offline development.
Preview Mode – The package is signed and automatically downloaded from Microsoft to test
computers with the appropriate registry settings configured. Preview Mode does not check to
ensure that the mobile broadband app is published to the Microsoft Store.
3-Insert the store manifest file into the Microsoft Store device app
A store manifest file must be included with a UWP device app. Use the following steps to download the store
manifest file from your service metadata package and insert it into the mobile broadband app project.
Inser t the store manifest file
1. On the Windows Dev Center hardware dashboard, on the manage experience page for your service
metadata package, click the service metadata package, and then click StoreManifest.xml to download
your store manifest file.
2. Open the mobile broadband app project by using Visual Studio 2013.
3. Right-click the project, click Add , and then click Existing Item .
4. Browse to the store manifest file that you downloaded, and then click Add .
5. Recompile the mobile broadband app and publish it again to the Microsoft Store.
4-Test the service metadata package
To test the service metadata package, you must have the mobile broadband device and the service metadata
package files. The instructions to configure your test system and install the service metadata package depend on
the mode of the package.
Test a service metadata package in developer mode
You must manually download the package and install it in the right location for the scenarios to work correctly.
Your developer mode package will need to be accessed from two different entry points depending on whether
you authored a new package or an existing package.
If you created a new package, in the Windows Dev Center hardware dashboard, click Manage experiences ,
and then click Unassociated Dev Packages (the first entry in the Manage experiences table). The following
figure shows an example:
If you edited an existing service metadata package that is already associated with an experience, select the
experience from the Manage experiences table, and you will see the developer mode package in the
Metadata packages table. Click Download MBAE Zip Package Edit to download it.
After you’ve download the service metadata package, you must enable test signing because the service
metadata package is not signed. To enable test signing, run bcdedit –set testsigning on from an elevated
command prompt and then restart your computer.
After test signing is enabled, copy the *.devicemetadata-ms file from the service metadata package to the
following location: %ProgramData%\Microsoft\Windows\DeviceMetadataStore\ culture, where culture is
the current culture code for your computer.
Test a service metadata package in preview mode
If the service metadata package is in preview mode, you must create the PreviewKey registry entry on your test
computer. For more info about configuring the PreviewKey registry entry, see Creating a Preview Package.
Note
You do not have to enable test signing to test a service metadata package that is in preview mode.
After the PreviewKey registry entry is created, plug in your mobile broadband device and ensure that it shows in
the Networks list. If it does not, see the Troubleshooting section for more info.
Clear the existing service metadata
When service metadata is installed on a PC, the values contained in the metadata are stored in many different
places, including the registry, metadata cache, metadata store, WWAN profiles and dev node. This can make it
challenging to repeat multiple tests with the same, or different, metadata packages. To ensure that the service
metadata is installed correctly, you should clear any existing service metadata. You can clear existing service
metadata by setting up your test computer to run a PowerShell script that removes all traces. First, you must set
up the environment on your test computer:
Note
This will not work on a Windows RT device. Use the steps in the procedure named “To clear service metadata on
a device running Windows RT”.
To set up the environment for clearing ser vice metadata
1. Download psexec.exe (https://go.microsoft.com/fwlink/p/?linkid=330071), and then extract it to a folder.
2. Download and install the Windows Driver Kit Windows 8.1 (https://go.microsoft.com/fwlink/?
LinkId=330072).
3. Navigate to where the WDK files are installed. The default location is C:\Program Files
(x86)\Windows Kits\8.1\Tools . If your test computer is running x86, copy devcon.exe from the x86
folder into the same folder as psexec.exe. If your test computer is running x64, copy devcon.exe from the
x64 folder.
4. Save the following script as MetadataRemovalScript.ps1 in the same folder as Devcon.exe and PsExec.exe.
Note
In the Save as type box, make sure to select All files (*.*) before saving the file.
Write-Host "Launching devcon to remove MBAE software device nodes devcon.exe remove @SWD\MBAE\*"
$DevconParameters = ' remove @SWD\MBAE\* '
try
{
Start-Process devcon.exe -ArgumentList $DevconParameters
}
catch
{
$Error[0] # Dump details about the last error
Write-Host "Error running devcon.exe " $DevconParameters
exit
}
if($tokens.Length -gt 3)
{
for($i=3;$i -lt $tokens.Length-1;$i++)
{
$x = $mddelprcmd + '"' + $tokens[$i].trim() +'"'
Write-Host "Deleting Profile Cmd :" $x
$x | netsh
}
}
Write-Host ""
Write-Host "Disabling ALL Mobile Broadband Adapters"
$MBAdapters = Get-Netadapter -Name "Mobile Broadband*"
foreach($MBAdapter in $MBAdapters)
{
Write-Host "Disabling MB Adapter :"$MBAdapter.Name
Disable-NetAdapter -Name $MBAdapter.Name -Confirm:$false
}
foreach($MBAdapter in $MBAdapters)
{
Write-Host "Enabling MB Adapter :"$MBAdapter.Name
Enable-NetAdapter -Name $MBAdapter.Name -Confirm:$false
}
Write-Host "Launching devcon to remove MBAE software device nodes devcon.exe remove @SWD\MBAE\*"
$DevconParameters = ' remove @SWD\MBAE\* '
try
{
Start-Process devcon.exe -ArgumentList $DevconParameters
Start-Process devcon.exe -ArgumentList $DevconParameters
}
catch
{
$Error[0] # Dump details about the last error
Write-Host "Error running devcon.exe " $DevconParameters
exit
}
if($tokens.Length -gt 3)
{
for($i=3;$i -lt $tokens.Length-1;$i++)
{
$x = $mddelprcmd + '"' + $tokens[$i].trim() +'"'
Write-Host "Deleting Profile Cmd :" $x
$x | netsh
}
}
Write-Host ""
Write-Host "Please remove the MB device from the system and press any key to continue"
$keypress = $host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")
After the environment is set up, run the following steps each time that you want to clear any existing service
metadata:
To clear the ser vice metadata
1. Ensure that the mobile broadband device is plugged into your test computer.
2. From an elevated command prompt, navigate to the folder where you extracted psexec.exe, and then run
psexec /s /i powershell
3. In the PowerShell command prompt, navigate to the folder where you extracted psexec.exe.
4. Type set-executionpolicy unrestricted and then press Enter.
5. Type Y and then Enter.
6. Type .\MetadataRemovalScript.ps1 and then press Enter.
7. When prompted, remove the mobile broadband device, and then press Enter.
8. Repeat these steps each time you want to clear the service metadata from your test computer.
To clear ser vice metadata on a device running Windows RT
1. Remove the software device nodes.
a. In Device Manager, click View , and then click Show hidden devices .
b. Expand Software devices.
c. Right-click the following device nodes, and then click Uninstall :
Windows.Devices.Sms.SmsDevice and
Windows.Networking/NetworkOperators.MobileBroadbandAccount
2. Remove all mobile broadband profiles from all interfaces.
a. From an elevated command prompt, type netsh mbn sho pro i=\ *
b. For each of the profiles, type netsh mbn delete profile name = “The profile name here”
i=\ * and then press Enter.
3. Disable all mobile broadband adapters.
a. In Device Manager, expand Network adapters .
b. Right-click each mobile broadband device, and then click Disable .
4. From an elevated command prompt, stop the DSM service by typing sc stop dsmsvc and then press
Enter.
5. Remove your service metadata packages from the device metadata store by deleting any folder that
contains your service metadata package from
%ProgramData%\Microsoft\Windows\DeviceMetadataStore . You can identify service metadata
packages by looking for the MobileBroadbandInfo.xml file.
6. Delete all WWAN SVC MBAE registry entries.
a. In Registry Editor, delete the following registry entry and all child entries:
HKEY_LOCAL_MACHINE\Software\Microsoft\WwanSvc\MobileBroadbandAccounts.
b. If you don’t have access to delete the registry entry, you must give yourself Full Control
permissions.
7. Enable all mobile broadband adapters.
a. In Device Manager, expand Network adapters .
b. Right-click each mobile broadband device, and then click Enable .
5-Publish the service metadata package
Once you have confirmed that the service metadata package works correctly, the final step is to release the
package. You can release the package by selecting the package attached to the specific experience by clicking the
Release button, as shown below.
Troubleshooting
Open the networks list and look for your mobile broadband network. If the network is listed by using the name
and icon that you used in the service metadata package Ser viceInfo.xml file, the package is correctly parsed. If
you are updating a service metadata package that has the same name and icon, or if the name or icon has not
appeared in the list after about approximately one minute, you should perform additional steps, as discussed
here:
Force a metadata refresh
Check the metadata cache
Check the registry
Check the WWAN Logs
Force a metadata refresh
Some parts of the metadata and mobile broadband app systems rely on network access, which can fail and
leave the computer in an inconsistent state. If this happens, you can encounter a situation where service
metadata is not installed or the mobile broadband app is not installed. The system periodically tries to remedy
the situation, but to conserve power, retries are fairly infrequent ( just a few times a day). Instead of waiting for
the next retry, you can manually force a refresh to happen immediately. To do this, perform the following steps:
1. Open the desktop Control Panel .
2. Open Devices and Printers .
3. From the View menu, click Refresh , or press the F5 key. This action causes metadata to be reparsed and
background events to be re-registered.
Impor tant
If a service metadata package has already been successfully parsed, the system will treat this refresh as a
metadata update. In this case, your metadata package must have a different GUID in its filename and an updated
timestamp in the LastModifiedDate element of PackageInfo.xml .
Check the metadata cache
If a metadata refresh did not fix the problem, make sure that the service metadata package is valid and that it
has the correct Hardware IDs. To do this, perform the following steps:
1. Navigate to %programdata%\Microsoft\Windows\DeviceMetadataCache\dmrccache\ culture,
where culture is the culture code for the current culture of your test computer (for example, en-us or es-
es ).
2. Look for a folder that has the same name as your metadata package (without the .devicemetadata-ms
extension). If this directory does not exist, it can mean one of four things:
The service metadata package is corrupt.
The service metadata package does not have the correct Hardware IDs.
The mobile broadband device is not in a state where metadata can be downloaded, or you plugged
in the device before you copied the service metadata package.
A problem occurred when checking the digital signature on the metadata package. This is usually
caused by not having test signing enabled on your test computer.
If you’re sure that the package is not corrupted and that you first plugged in the mobile broadband device after
you copied the service metadata package, check the IMSI ranges. It’s very easy to type in too many or too few 0s
or 9s. If the problem persists after confirming or correcting these items, you must look at the registry.
Check the registry
Warning
You should not edit registry data that does not belong to your application unless it is absolutely necessary. If
there is an error in the registry, your system might not function properly. Do not, under any circumstances,
delete the MobileBroadbandAccounts registry key. Windows will not re-create it and you will break the
feature.
Perform the following steps to check the registry:
1. Open Registry Editor.
2. Go to HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts .
3. Inside this registry key, look for three other keys: Accounts , NetworkInterfaceBindings , and Data .
These keys do not exist by default; they are automatically created the first time that a mobile broadband
device is inserted, turned on, or connected.
4. If the Accounts or NetworkInterfaceBindings keys do not exist and you have already plugged in or
turned on your mobile broadband adapter, check the WWAN logs.
5. If some or all of these keys exist, expand the Accounts key in the Tree view. One or more registry keys
that have names similar to GUIDs should exist inside it. The registry tree entries should be similar to the
registry tree that is displayed below:
If the registry key looks similar to the above figure (the value names will vary slightly depending on
whether the account is on a GSM or CDMA network), and if you do not see the icon in the networks list,
you should look at the event logs.
If the Registry entries are similar to the next figure, it means that the mobile broadband adapter was
inserted before the service metadata package was copied into the device metadata store, the service
metadata package is corrupted, or the Hardware IDs are incorrect. To remedy a situation where you
plugged in or turned on the device before copying the metadata package into the metadata store,
perform the steps in Force a metadata refresh. Otherwise, follow the steps in Check the WWAN Logs.
You can find these entries by searching the log for Account Management . In this case, the most important
entries are Data store create/update star ted and Data store create/update finished . If these entries exist
and have no error messages, the hardware is behaving correctly. (The data store that is referred to here contains
the registry keys that are discussed in Check the registry.)
By contrast, on a device where the SIM is removed, the entries typically look like the following:
These logs show that the MobileBroadbandInfo.xml file was correctly parsed, that the parser task applied the
WWAN profiles (together with the WWAN service logging that successfully updated the profiles), and that the
parser task set the trusted provisioning certificates mentioned in MobileBroadbandInfo.xml .
If any part of the process failed, that failure is logged. For example, if the digital signature check fails on the
service provider icon file, log entries typically look like the following:
[0]0F24.0C70::2012-01-04 10:09:49.271 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task
started.
[0]0F24.0C70::2012-01-04 10:09:49.288 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parsing
metadata for device container with id "{97223B34-36F4-11E1-BC81-00155DE96B01}" for culture "en-US".
[0]0F24.0C70::2012-01-04 10:09:49.483 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Starting
parse of mobile broadband service information file.
[0]0F24.0C70::2012-01-04 10:09:49.483 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Metadata
package contains no data for culture "en-US". Using fallback data.
[0]0F24.0C70::2012-01-04 10:09:49.547 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Finished
parse of mobile broadband service information file.
[0]0F24.0C70::2012-01-04 10:09:49.547 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Starting
update of stored network account information.
[0]0F24.0C70::2012-01-04 10:09:49.688 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Digital
signature verification failed for file "c:\programdata\microsoft\windows\devicemetadatacache\dmrccache\en-
us\B68264FF-E4D1-49B1-AB5F-2B9C1C16EF5D\ServiceInformation\ContosoBroadband.ico".
[0]0F24.0C70::2012-01-04 10:09:49.690 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Finished
update of stored network account information.
[0]0F24.0C70::2012-01-04 10:09:49.692 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task
finished.
[0]0F24.0C70::2012-01-04 10:09:49.692 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-
Task]MbaeParserTask did not complete successfully. Error is 0x80070306: One or more errors occurred while
processing the request.
Because it is normal for the parser task to run more than one time, you might see more than one set of
[Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task] log entries. In this case, the sets of entries are
typically the same - if they are not the same, it can indicate an intermittent problem.
Additional resources
Use the following links to learn more about mobile broadband in Windows 8.1 and Windows 10:
Overview of mobile broadband
APN database overview
Service metadata
Service identifier ownership updates
4/13/2022 • 2 minutes to read • Edit Online
Service Identifiers are a set of fields that are encoded in mobile broadband devices (SIM cards for GSM and
modem for CDMA) and are used to uniquely identify the device. The service identifier is used by Windows 8,
Windows 8.1, and Windows 10 to download the service metadata package for that device. Before you create
your service metadata packages, you must register your service identifiers with the Windows Dev Center
hardware dashboard. For info on registering new service identifiers, see Developer guide for creating service
metadata.
Depending on the technology, service identifiers can consist of the following:
GSM
Provider ID The combination of mobile country code and mobile network code, which is a 5 or 6
digit number.
Provider Name The name flashed on to the device when the firmware is provisioned.
CDMA
SID The System Identifier (SID) of a CDMA network.
Provider Name The name flashed on to the device when the firmware is provisioned.
If the ownership of an IMSI changes, the new operator must send an email to sysdev@microsoft.com with the
following info:
Organization name used by the operator during the Windows Dev Center hardware dashboard
registration process
Name of the old mobile operator that owned the IMSI
List of GSM Provider IDs affected by the ownership change
You should receive an acknowledgement emails with 24 hours that your request was received. However, it could
take up to 5 business days to process the request. If we have conflicts, we’ll send you an email asking for
additional information.
MobileBroadbandInfo XML schema overview
4/13/2022 • 2 minutes to read • Edit Online
A service metadata package contains one MobileBroadbandInfo.xml document, which contains information that
is specific to mobile broadband networks.
The data within the MobileBroadbandInfo.xml document is formatted based on the MobileBroadbandInfo XML
schema, which is described in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the MobileBroadbandInfo XML schema, see MobileBroadbandInfo XML schema
definition.
For information about the elements that are defined by the MobileBroadbandInfo XML schema, see
MobileBroadbandInfo XML elements.
For an example of XML data in the format that is defined by the MobileBroadbandInfo XML schema, see
MobileBroadbandInfo XML example.
MobileBroadbandInfo XML schema definition
4/13/2022 • 2 minutes to read • Edit Online
http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo
<xs:schema
targetNamespace="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo"
xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" blockDefault="#all">
</xs:schema>
MobileBroadbandInfo XML elements list
4/13/2022 • 2 minutes to read • Edit Online
This section describes the XML elements defined by the MobileBroadbandInfo XML schema. The following is a
list of these elements in the order in which they are defined in the XML schema.
MobileBroadbandInfo
NetworkConfiguration
MobileBroadbandProfiles
Purchase
Internet
AllowStandardUserPinUnlock
AllowTethering
ProvisioningEngine
TrustedCertificates
TrustedCertificate
SubjectName
IssuerName
MobileBroadbandInfo
4/13/2022 • 2 minutes to read • Edit Online
The MobileBroadbandInfo element is the parent element of the MobileBroadbandInfo XML schema.
Usage
<MobileBroadbandInfo>
child elements
</MobileBroadbandInfo>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
There are no parent elements.
XSD
<xs:element name="MobileBroadbandInfo" type="tns:MobileBroadbandInfoType" />
<xs:complexType name="MobileBroadbandInfoType">
<xs:sequence>
<xs:element name="NetworkConfiguration" type="tns:NetworkConfigType" minOccurs="0" />
<xs:element name="ProvisioningEngine" type="tns:ProvisioningEngineType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The MobileBroadbandInfo element is required.
NetworkConfiguration
4/13/2022 • 2 minutes to read • Edit Online
The NetworkConfiguration element specifies the purchase and Internet mobile broadband profiles to be used.
The files that are referenced in this element should be included in the Ser viceInformation directory. These
files help in getting users connected to the operator network. It also specifies whether standard users should be
allowed to perform PIN unlock operations on their Mobile Broadband SIMs.
Usage
<NetworkConfiguration>
child elements
</NetworkConfiguration>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="NetworkConfiguration" type="tns:NetworkConfigType" minOccurs="0" />
<xs:complexType name="NetworkConfigType">
<xs:sequence>
<xs:element name="MobileBroadbandProfiles" type="tns:MobileBroadbandProfilesType" minOccurs="0" />
<xs:element name="AllowStandardUserPinUnlock" type="xs:boolean" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
In order to set a plan purchase APN or an Internet connection APN, the mobile network operator (MNO)
should specify the XML profiles that correspond to these states as part of this element.
The child elements in this element are optional. If these are not specified, the APN values from the APN
database included with Windows are used to help the user get connected.
Typically, only users in the Administrators security group are allowed to perform PIN unlock operations
on their Mobile Broadband SIMs. However, setting the AllowStandardUserPinUnlock element to true
allows the mobile operator to specify whether standard users are allowed to perform this function.
MobileBroadbandProfiles
4/13/2022 • 2 minutes to read • Edit Online
The MobileBroadbandProfiles element specifies the purchase and Internet mobile broadband profile files to use.
Usage
<MobileBroadbandProfiles>
child elements
</MobileBroadbandProfiles>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="MobileBroadbandProfiles" type="tns:MobileBroadbandProfilesType" minOccurs="0" />
<xs:complexType name="MobileBroadbandProfilesType">
<xs:sequence>
<xs:element name="Purchase" type="tns:FileType" minOccurs="0" />
<xs:element name="Internet" type="tns:FileType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The MobileBroadbandProfiles element is optional.
Purchase
4/13/2022 • 2 minutes to read • Edit Online
The Purchase element specifies the purchase mobile broadband profile file to use.
Usage
<Purchase>
child element
</Purchase>
Attributes
There are no attributes.
Text value
The name of a file in the ServiceInformation directory.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Purchase" type="tns:FileType" minOccurs="0"/>
<xs:simpleType name="FileType">
<xs:restriction base="xs:string">
<xs:whiteSpace value="preserve"/>
<xs:pattern value="[\p{L}\p{N}\.\-_ ]+"/>
<xs:minLength value="1"/>
<xs:maxLength value="260"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Purchase element is optional.
Internet
4/13/2022 • 2 minutes to read • Edit Online
The Internet element specifies the purchase mobile broadband profile file to use.
Usage
<Internet>
child element
</Internet>
Attributes
There are no attributes.
Text value
The name of a file in the ServiceInformation directory.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Internet" type="tns:FileType" minOccurs="0"/>
<xs:simpleType name="FileType">
<xs:restriction base="xs:string">
<xs:whiteSpace value="preserve"/>
<xs:pattern value="[\p{L}\p{N}\.\-_ ]+"/>
<xs:minLength value="1"/>
<xs:maxLength value="260"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Internet element is optional.
AllowStandardUserPinUnlock
4/13/2022 • 2 minutes to read • Edit Online
IMPORTANT
Starting in Windows 10, version 1507, this element has been deprecated and may not be supported in future versions of
Windows.
The AllowStandardUserPinUnlock element specifies if standard users are allowed to perform PIN unlock
operations.
Usage
<AllowStandardUserPinUnlock>
text
</ AllowStandardUserPinUnlock >
Attributes
There are no attributes.
Text value
A Boolean value where true allows standard users to perform PIN unlock operations and false does not.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="AllowStandardUserPinUnlock" type="xs:boolean" minOccurs="0" />
Remarks
The AllowStandardUserPinUnlock element is optional.
AllowTethering
4/13/2022 • 2 minutes to read • Edit Online
The AllowTethering element specifies whether the user is always allowed, never allowed, or allowed after an
entitlement check to use Internet sharing.
Note If this element is configured to allow after an entitlement check, you must specify a
DeviceNotificationHandler in your app that will handle the entitlement check.
Usage
<AllowTethering>
text
</AllowTethering>
Attributes
There are no attributes.
Text value
A string indicating whether Internet sharing is always allowed, never allowed, or allowed after an entitlement
check.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="name="AllowTethering" type="tns:TetheringAllowedType" minOccurs="0" />
<xs:simpleType name="TetheringAllowedType">
<xs:restriction base="xs:string">
<xs:enumeration value="Never"/>
<xs:enumeration value="Always"/>
<xs:enumeration value="EntitlementCheckRequired"/>
</xs:restriction>
</xs:simpleType>
Remarks
This element is only applicable to Windows 8.1 and Windows 10.
The AllowTethering element is optional.
ProvisioningEngine
4/13/2022 • 2 minutes to read • Edit Online
The ProvisioningEngine element specifies the trusted certificates. This allows operators to provision the PC with
packages that are signed with a trusted certificate.
For more information about provisioning, see Account provisioning.
Usage
<ProvisioningEngine>
child element
</ProvisioningEngine>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ProvisioningEngine" type="tns:ProvisioningEngineType" minOccurs="0" />
<xs:complexType name="ProvisioningEngineType">
<xs:sequence>
<xs:element name="TrustedCertificates" type="tns:TrustedCertificateListType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
Windows 8, Windows 8.1, and Windows 10 allow mobile network operators to provide packages to make
updates to the user’s mobile broadband network settings called provisioning packages.
To ensure those provisioning packages come from the mobile network operator, Windows verifies that
the Issuer Name and Subject Name from the certificate that is used to sign the provisioning package
match what is described in the service metadata package.
The ProvisioningEngine element is optional.
TrustedCertificates
4/13/2022 • 2 minutes to read • Edit Online
Usage
<TrustedCertificates>
child elements
</TrustedCertificates>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="TrustedCertificates" type="tns:TrustedCertificateListType" minOccurs="0" />
<xs:complexType name="TrustedCertificateListType">
<xs:sequence>
<xs:element name="TrustedCertificate" type="tns:TrustedCertificateType" minOccurs="0" maxOccurs="256" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The TrustedCertificates element is optional.
TrustedCertificate (MobileBroadbandInfo)
4/13/2022 • 2 minutes to read • Edit Online
The TrustedCertificate element specifies the Subject Name and Issuer name of a trusted certificate.
Usage
<TrustedCertificate>
child elements
</TrustedCertificate>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="TrustedCertificate" type="tns:TrustedCertificateType" minOccurs="0" maxOccurs="256" />
<xs:complexType name="TrustedCertificateType">
<xs:sequence>
<xs:element name="SubjectName" type="xs:string" />
<xs:element name="IssuerName" type="xs:string" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The TrustedCertificate element is optional.
SubjectName
4/13/2022 • 2 minutes to read • Edit Online
Usage
<SubjectName>
text
</SubjectName>
Attributes
There are no attributes.
Text value
A string with the Subject Name of the certificate.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="SubjectName" type="xs:string" />
Remarks
The SubjectName element is optional.
IssuerName
4/13/2022 • 2 minutes to read • Edit Online
Usage
<IssuerName>
text
</IssuerName>
Attributes
There are no attributes.
Text value
A string with the Issuer Name of the certificate.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="IssuerName" type="xs:string" />
Remarks
The IssuerName element is optional.
MobileBroadbandInfo XML example
4/13/2022 • 2 minutes to read • Edit Online
The following XML document uses the MobileBroadbandInfo XML schema to specify the mobile broadband
specific information for the service:
A metadata package contains one PackageInfo.xml document, which has information that the operating system
uses to install the metadata package and reference its contents.
The data in the PackageInfo.xml document is formatted based on the PackageInfo XML schema, which is
described in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the PackageInfo XML schema, see PackageInfo XML schema definition.
For information about the elements that are defined by the PackageInfo XML schema, see PackageInfo XML
elements.
For information about the data types that are defined by the PackageInfo XML schema, see PackageInfo XML
data types.
For an example of XML data in the format that is defined by the PackageInfo XML schema, see PackageInfo XML
Example.
PackageInfo XML schema definition
4/13/2022 • 2 minutes to read • Edit Online
http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2
<xs:import namespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
schemaLocation="PackageInfov2.xsd" />
<xs:complexType name="PackageInfoType">
<xs:sequence>
<xs:element name="MetadataKey" type="tns:MetadataKeyType" />
<xs:element name="PackageStructure" type="tns:PackageStructureType" />
<xs:element name="Relationships" type="tns:RelationshipsType" minOccurs="0" />
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0"
/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataKeyType">
<xs:sequence>
<xs:choice>
<xs:sequence>
<xs:element name="HardwareIDList" type="tns:HardwareIDListType" />
<xs:element name="ModelIDList" type="tns:ModelIDListType" minOccurs="0" />
</xs:sequence>
<xs:element name="ModelIDList" type="tns:ModelIDListType" />
</xs:choice>
<xs:element name="Locale" type="tns:LocaleType" />
<xs:element name="LastModifiedDate" type="xs:dateTime" />
<xs:element ref="v2:MultipleLocale" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ModelIDListType">
<xs:complexType name="ModelIDListType">
<xs:sequence>
<xs:element name="ModelID" type="tns:GUIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="GUIDType">
<xs:restriction base="xs:string">
<xs:pattern value= "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="HardwareIDListType">
<xs:sequence>
<xs:element name="HardwareID" type="tns:HardwareIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="HardwareIDType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="207" />
<xs:pattern value="^([a-zA-Z0-9!#$%&()*+\-./:;<=>?@[\\\]^_`{|}~])*$" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="LocaleType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="default" type="xs:boolean" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="PackageStructureType">
<xs:sequence>
<xs:element name="Metadata" type="tns:MetadataType" minOccurs="2" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="MetadataID" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="RelationshipsType">
<xs:sequence>
<xs:element name="ExperienceID" type="tns:GUIDType" minOccurs="0" />
<xs:element name="LanguageNeutralIdentifier" type="tns:GUIDType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataBuilderInformationType">
<xs:sequence>
<xs:element name="Application" type="tns:ApplicationType" />
<xs:element name="Version" type="tns:VersionType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ApplicationType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="VersionType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
</xs:schema>
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
blockDefault="#all">
</xs:schema>
PackageInfo XML elements list
4/13/2022 • 2 minutes to read • Edit Online
This section describes the XML elements defined by the PackageInfo XML schema. The following is a list of these
elements in the order in which they are defined in the XML schema.
PackageInfo
MetadataKey
ModelIDList
ModelID
HardwareIDList
HardwareID
Locale
LastModifiedDate
MultipleLocale
PackageStructure
Metadata
Relationships
ExperienceID
LanguageNeutralIdentifier
MetadataBuilderInformation
Application
Version
PackageInfo
4/13/2022 • 2 minutes to read • Edit Online
The PackageInfo element is the parent element of the PackageInfo XML schema. The child elements of the
PackageInfo element specify the attributes of the service metadata package.
Usage
<PackageInfo>
child elements
</PackageInfo>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="PackageInfo" type="tns:PackageInfoType" />
<xs:complexType name="PackageInfoType">
<xs:sequence>
<xs:element name="MetadataKey" type="tns:MetadataKeyType" />
<xs:element name="PackageStructure" type="tns:PackageStructureType" />
<xs:element name="Relationships" type="tns:RelationshipsType" minOccurs="0" />
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The PackageInfo element must contain one instance of the MetadataKey, PackageStructure, and Relationships
elements.
MetadataKey
4/13/2022 • 2 minutes to read • Edit Online
The MetadataKey element specifies the attributes of the service metadata package. These include the following:
The identifier for each hardware function supported by the device.
The language-specific locale for the text strings within the package.
Usage
<MetadataKey>
child elements
</MetadataKey>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="MetadataKey" type="tns:MetadataKeyType" />
<xs:complexType name="MetadataKeyType">
<xs:sequence>
<xs:choice>
<xs:sequence>
<xs:element name="HardwareIDList" type="tns:HardwareIDListType" />
<xs:element name="ModelIDList" type="tns:ModelIDListType" minOccurs="0" />
</xs:sequence>
<xs:element name="ModelIDList" type="tns:ModelIDListType" />
</xs:choice>
<xs:element name="Locale" type="tns:LocaleType" />
<xs:element name="LastModifiedDate" type="xs:dateTime" />
<xs:element ref="v2:MultipleLocale" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
blockDefault="#all">
</xs:schema>
Remarks
The child elements of the MetadataKey element specify the metadata that the operating system uses to do the
following:
Search the device metadata store for a service metadata package based on either a device's ModelID or
HardwareID value. If more than one metadata packages match the device's Model or Hardware ID, the
operating system also compares the Locale value within the metadata package to the current language
setting on the user's computer.
Update the device metadata store with the service metadata package if a package has a more recent
LastModifiedDate value than an existing package within the device metadata store.
The MetadataKey element must contain:
One instance of the Locale and LastModifiedDate elements.
One instance of either the HardwareIDList or ModelIDList elements. The MetadataKey element can
contain one instance of both elements.
The MetadataKey element is required.
ModelIDList
4/13/2022 • 2 minutes to read • Edit Online
The ModelIDList element specifies one or more GUIDs. Each GUID is specified through a ModelID element, and
identifies a physical device specified within the device metadata package.
Caution The ModelIDList and ModelID elements are not supported for service metadata packages. You must
use the HardwareIDList and HardwareID elements instead.
Usage
<ModelIDList>
child elements
</ModelIDList>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ModelIDList" type="tns:ModelIDListType" minOccurs="0" />
<xs:complexType name="ModelIDListType">
<xs:sequence>
<xs:element name="ModelID" type="tns:GUIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The ModelIDList element is required only if the HardwareIDList element is not specified in the MetadataKey
element. If it is specified, the ModelIDList element must contain one or more ModelID elements. If your device
metadata package supports multiple device models or model IDs, you can specify a ModelID element for each
device model.
Caution The ModelIDList and ModelID elements are not supported for service metadata packages. You must
use the HardwareIDList and HardwareID elements instead.
If the PackageInfo XML data contains both of the HardwareIDList and ModelIDList elements, the operating
system uses the following rules when it determines whether a device is specified by a device metadata package:
If the device has a model ID, the operating system does not search for a match in the HardwareIDList
element. For more information about model IDs, see ModelID.
Otherwise, the operating searches the HardwareIDList element for a match of the device's hardware ID.
ModelID
4/13/2022 • 2 minutes to read • Edit Online
Usage
<ModelID>
text
</ModelID>
Attributes
There are no attributes.
Text value
A value formatted as a GUIDType XML simple type.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
Remarks
The ModelID element specifies a model ID for a hardware model supported by a device. Each model ID is
specified through a GUID.
Caution The ModelIDList and ModelID elements are not supported for service metadata packages. You must
use the HardwareIDList and HardwareID elements instead.
Model IDs are based on the business definition or SKU of the physical device. Each model ID must be unique for
all makes and models of the physical device.
The following list describes the differences between hardware and model IDs for a physical device:
Hardware IDs, specified through the HardwareID element, identify a hardware function based on a bus-
specific value. Hardware IDs could map device drivers to device instances. For example, two devices with
the same hardware ID share a functional interface that is used by the same driver.
Model IDs, specified through the ModelID element, enable the OEM or independent hardware vendor
(IHV) to uniquely identify the physical device independent of bus or interface technologies. For example,
two devices with different model IDs may have the same hardware IDs for their components.
Hardware IDs map device metadata packages to device instances on a specific bus or interface.
Model IDs map device metadata packages to physical devices, regardless of how the device is connected
to the computer.
HardwareIdList (PackageInfo)
4/13/2022 • 2 minutes to read • Edit Online
The HardwareIDList element specifies one or more hardware identification strings for the service metadata
package. Each string is specified by a HardwareID element.
Usage
<HardwareIDList>
child elements
</HardwareIDList>
Attributes
There are no attributes.
Text value
Must contain one or more HardwareID elements.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
<xs:complexType name="HardwareIDListType">
<xs:sequence>
<xs:element name="HardwareID" type="tns:HardwareIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The HardwareIDList element is required.
HardwareId (PackageInfo)
4/13/2022 • 2 minutes to read • Edit Online
For service metadata packages, the HardwareID values represent the mobile network operator in the form of the
following:
GSM networks: IMSI value
GSM networks: ICCID value
CDMA networks: Provider name value
CDMA networks: Provider ID value (also known as a SID)
Usage
<HardwareID>
text
</HardwareID>
Attributes
There are no attributes.
Text value
Generating the proper hardware ID values as part of metadata creation involves a complex algorithm. You
should generate hardware ID values by using MBIDGenerator.exe included in the Windows Driver Kit (WDK).
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
<xs:simpleType name="HardwareIDType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="207" />
<xs:pattern value="^([a-zA-Z0-9!#$%&()*+\-./:;<=>?@[\\\]^_`{|}~])*$" />
</xs:restriction>
</xs:simpleType>
Remarks
Hardware IDs that are included in PackageInfo.xml must have the “DOID:” prefix added to them. For
example: DOID:MBAE:0:hashednumber1
More than one HardwareID element can be used to specify a service.
For GSM IMSI or ICCID ranges, the start range value must end in 00 and the end range value must end in
99. For privacy reasons, matching occurs in blocks of 100 for IMSI and ICCID values.
The HardwareID element is required.
Locale
4/13/2022 • 2 minutes to read • Edit Online
The Locale element specifies the locale of the service metadata package. A service metadata package can specify
single or multiple locales. To use multiple locales, you must set the MultipleLocale element to true .
Usage
<Locale
default = "xs:boolean">
text
</Locale>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Locale" type="tns:LocaleType" />
<xs:complexType name="LocaleType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="default" type="xs:boolean" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
The Locale element can be <Language>-<Region> (such as EN-US) or <Language> (such as EN). If the
<Language> is set, the package applies to all <Language> locales. For example, EN applies to EN-US and
EN-BR.
To specify the metadata package as the default for the current locale of the computer, set the default
attribute to true (1).
Note Only one metadata package for a service should set the default attribute to true (1). Otherwise,
the operating system randomly selects a metadata package for the service.
When the operating system selects a service metadata package to display, it uses the Locale element in
the following way:
1. The operating system retrieves the system preferred language and region. This is typically
configured during Windows Setup.
2. If the Locale element of a service metadata package matches the system preferred language and
region, the operating system selects the package for the service and uses the icon and
Ser viceProvider value (from ServiceInfo.xml) that matches that language and region.
3. If the services metadata package does not have a Locale element that matches the system
preferred language, the operating system will apply the language neutral icon and
Ser viceProvider value (from ServiceInfo.xml) that is stored in the root of the service metadata
package.
The Locale element is required.
LastModifiedDate
4/13/2022 • 2 minutes to read • Edit Online
The LastModifiedDate element specifies the timestamp on which the service metadata package was last
changed. Based on this information, the operating system selects and loads the most recent service metadata
package version.
Usage
<LastModifiedDate>
text
</LastModifiedDate>
Attributes
There are no attributes.
Text value
The timestamp value is represented in the Universal Time Coordinated (UTC) format.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="LastModifiedDate" type="xs:dateTime" />
Remarks
The value of the LastModifiedDate element must represent the actual time that the metadata package
was last changed.
Each time you submit your service metadata package to the Windows Hardware Dev Center Dashboard
for distribution through Windows Metadata and Internet Services (WMIS), the LastModifiedDate element
is updated after your package is validated.
The LastModifiedDate element is required.
MultipleLocale
4/13/2022 • 2 minutes to read • Edit Online
The MultipleLocale element specifies if the service metadata package supports multiple locales or not.
Usage
<MultipleLocale>
text
</MultipleLocale>
Attributes
There are no attributes.
Text value
A boolean value that is true if the service metadata package supports multiple locales.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="MultipleLocale" type ="xs:boolean" />
Remarks
To support multiple locales in the service metadata package , Set the MultipleLocale element to true . This
element is not supported on Windows 7. If this element is not specified, the default value is true.
If there is both a single locale service metadata package and a multiple-locale service metadata package
on a user's computer, Windows uses the multiple-locale service metadata package, if all other ranking
values are the same.
PackageStructure
4/13/2022 • 2 minutes to read • Edit Online
The PackageStructure element specifies the XML schemas that are referenced by the service metadata package.
Each XML schema is specified through the Metadata element.
Usage
<PackageStructure>
text
child elements
</PackageStructure>
Attributes
There are no attributes.
Text value
Four or more Metadata elements are required.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="PackageStructure" type="tns:PackageStructureType" />
<xs:complexType name="PackageStructureType">
<xs:sequence>
<xs:element name="Metadata" type="tns:MetadataType" minOccurs="2" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
A minimum of four instances of the Metadata element must be specified within the PackageStructure element.
Each instance must specify one of the required XML schemas that are used to create a service metadata
package:
PackageInfo XML schema
ServiceInfo XML schema
SoftwareInfo XML schema
MobileBroadbandInfo XML schema
The PackageStructure element is required.
Metadata
The Metadata element specifies the namespaces of the XML schemas that are referenced in the service metadata
package.
Usage
<Metadata
MetadataID = "xs:anyURI">
text
</Metadata>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Text value
The Uniform Resource Identifier (URI) of the namespace of a service metadata XML schema. The XML schema
must be one of the schemas referenced within the services metadata package.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="PackageStructure" type="tns:PackageStructureType" />
<xs:complexType name="PackageStructureType">
<xs:sequence>
<xs:element name="Metadata" type="tns:MetadataType" minOccurs="3" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="MetadataID" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
In the PackageInfo element, a minimum of two instances of the Metadata element must be specified. Each
instance must specify the namespace of one of the following required XML schemas that are used to create a
service metadata package:
PackageInfo XML schema
ServiceInfo XML schema
WindowsInfo XML schema
SoftwareInfo XML schema
The easiest approach is to copy the following example above into your Packageinfo.xml file. If any of the folders
specified above are not included in the service metadata package, make sure to remove the Metadata element
from the PackageStructure element.
<PackageStructure>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11">PackageInfo.xml</Metada
ta>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo">ServiceInformation</Met
adata>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/">WindowsInformation</Me
tadata>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo">SoftwareInformation</M
etadata>
</PackageStructure>
The SoftwareInformation folder and service metadata packages are not supported on devices running Windows
7.
Each folder name can be changed to an arbitrary name as long as the name is set in this metadata element. The
following example shows how to use “WindowsInfo” as a folder name:
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/">WindowsInfo</Metadata>
Relationships
4/13/2022 • 2 minutes to read • Edit Online
The Relationships element specifies data that is used to track a device metadata package within the device
metadata cache.
Usage
<Relationships>
text
child elements
</Relationships>
Attributes
There are no attributes.
Text value
If the Relationships element is specified, it must specify the ExperienceID element or the
LanguageNeutralIdentifier element, or both.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Relationships" type="tns:RelationshipsType" minOccurs="0" />
<xs:complexType name="RelationshipsType">
<xs:sequence>
<xs:element name="ExperienceID" type="tns:GUIDType" minOccurs="0" />
<xs:element name="LanguageNeutralIdentifier" type="tns:GUIDType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"
</xs:sequence>
</xs:complexType>
Remarks
The child elements of the Relationships element (ExperienceID and LanguageNeutralIdentifier) provide separate
search keys that the operating system uses to query device metadata packages that are installed within the
device metadata cache.
ExperienceID
4/13/2022 • 2 minutes to read • Edit Online
The ExperienceID element specifies a GUID representing the device experience. This GUID is used to group one
or more metadata packages for the same device identifiers independent of the packages’ locale.
In Windows 8, Windows 8.1, and Windows 10 it is also used to link the device metadata to a device app that can
be automatically acquired when the device is first connected. A device app specifies one or more ExperienceID
elements in a StoreManifest.XML file in the app submission package. Each of these ExperienceID GUIDs
corresponds to the ExperienceID element of a device metadata package. After the StoreManifest.xml file has
been submitted, the device app can then be distributed to one or more device models, if the ExperienceID in a
device’s metadata is also specified in the device apps StoreManifest file.
Usage
<ExperienceID>
text
</ExperienceID>
Attributes
There are no attributes.
Text value
A value formatted as a GUIDType XML simple type.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ExperienceID" type="tns:GUIDType" minOccurs="0" />
Remarks
In Windows 8.1 and Windows 10, the ExperienceID is created by the Service Metadata Wizard on the Windows
Dev Center Dashboard.
In Windows 8 the ExperienceID can be specified by the service metadata developer, or automatically generated
and added to the service metadata using the Device Metadata Authoring Wizard. If the ExperienceID is not
specified in the service metadata package, the Windows Dev Center Dashboard creates a GUID and updates the
ExperienceID element within the metadata package when the mobile network operator or mobile virtual
network operator submits the service metadata package.
LanguageNeutralIdentifier
4/13/2022 • 2 minutes to read • Edit Online
The LanguageNeutralIdentifier element specifies a GUID, which identifies the service metadata package
independent of its locale. The LanguageNeutralIdentifier element lets the same GUID be used to identify one or
more localized versions of a service metadata package for the same service.
Usage
<LanguageNeutralIdentifier>
text
</LanguageNeutralIdentifier>
Attributes
There are no attributes.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="LanguageNeutralIdentifier" type="tns:GUIDType" minOccurs="0" />
Remarks
The LanguageNeutralIdentifier element allows the same GUID to be used in one or more localized versions of a
device metadata package for the same device.
For example, If you release a device for three locales (such as EN-US, JA-JP, and AR-SA), you can create separate
metadata packages for the device for each locale. By using a common GUID for the LanguageNeutralIdentifier
elements in these packages, you can easily search for the device's metadata package by browsing its
PackageInfo XML document.
Impor tant The LanguageNeutralIdentifier element is not used by any component of the operating system. It is
reserved for use by the OEM, independent hardware vendor (IHV), and independent software vendor (ISV).]
The LanguageNeutralIdentifier element is optional.
MetadataBuilderInformation
4/13/2022 • 2 minutes to read • Edit Online
The MetadataBuilderInformation element specifies information about the application that created the device
metadata package.
Usage
<MetadataBuilderInformation>
text
child elements
</MetadataBuilderInformation>
Attributes
There are no attributes.
Text value
A string that contains between 1 and 256 printable characters inclusive.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0" />
<xs:complexType name="MetadataBuilderInformationType">
<xs:sequence>
<xs:element name="Application" type="tns:ApplicationType" />
<xs:element name="Version" type="tns:VersionType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ApplicationType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="VersionType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
Remarks
The MetadataBuilderInformation element is not used by any component of the operating system. It is reserved
for use by the OEM, IHV, and ISV.
Application
4/13/2022 • 2 minutes to read • Edit Online
The Application element specifies the name of the application software that created the device metadata
package.
Usage
<Application>
text
</Application>
Attributes
There are no attributes.
Text value
A string that contains between 1 and 256 characters inclusive.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Application" type="tns:ApplicationType" />
<xs:simpleType name="ApplicationType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
Remarks
The Application element is not used by the Windows 7 operating system. It is reserved for use by OEMs and
developers.
Version
4/13/2022 • 2 minutes to read • Edit Online
The Version element specifies the version of the application software that created the service metadata package.
Usage
<Version>
text
</Version>
Attributes
There are no attributes.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Version" type="tns:VersionType" />
<xs:simpleType name="VersionType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="256" />
</xs:restriction>
</xs:simpleType>
Remarks
The Version element is not used by the Windows 7 operating system. It is reserved for use by the OEM and
developers.
GUIDType (PackageInfo)
4/13/2022 • 2 minutes to read • Edit Online
<xs:simpleType name="GUIDType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
Patterns
The GUIDType simple type is a xs:string that is restricted by the following pattern:
[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
Remarks
The GUIDType XML simple type specifies a GUID that uniquely identifies components within the device metadata
package, such as the device's ExperienceID, LanguageNeutralIdentifier, and ModelID values.
PackageInfo XML Example
4/13/2022 • 2 minutes to read • Edit Online
The following XML document uses the PackageInfo XML schema to specify the components of a vendor’s
metadata package.
The package is for a service that has the following hardware ID:
MBAE:0:L9@E}}DT2.*F65MQA57Y+L
NOTE
Hardware IDs that are included in PackageInfo.xml must have the “DOID:” prefix added to them.
The package is also for the EN-US locale, which the document sets as the default locale for the components of
the metadata package.
<PackageInfo xmlns=http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/
xmlns:v2=” http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2”>
<MetadataKey>
<HardwareIDList>
<HardwareID>DOID:MBAE:0:L9@E}}DT2.*F65MQA57Y+L</HardwareID>
</HardwareIDList>
<Locale default="true">EN-US</Locale>
<LastModifiedDate>2008-01-24T00:00:00Z</LastModifiedDate>
<v2:MultipleLocale>true</v2:MultipleLocale>
</MetadataKey>
<PackageStructure>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11">PackageInfo.xml</Metada
ta>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/ServiceInfo/2007/11/">ServiceInformation</Me
tadata>
<Metadata
MetadataID=”http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/”>WindowsInformation</Me
tadata>
</PackageStructure>
</PackageInfo>
ServiceInfo XML schema overview
4/13/2022 • 2 minutes to read • Edit Online
A service metadata package contains one ServiceInfo.xml document, which contains detailed information about
the service that Windows Connection Manager displays to the user.
The data in the ServiceInfo.xml document is formatted based on the ServiceInfo XML schema, which is described
in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the ServiceInfo XML schema, see ServiceInfo XML Schema Definition.
For information about the elements that are defined by the ServiceInfo XML schema, see ServiceInfo XML
Elements.
For information about the data types that are defined by the ServiceInfo XML schema, see ServiceInfo XML Data
Types.
For an example of XML data in the format that is defined by the ServiceInfo XML schema, see ServiceInfo XML
Example.
ServiceInfo XML Schema Definition
4/13/2022 • 2 minutes to read • Edit Online
http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo
<xs:complexType name="ServiceInfoType">
<xs:sequence>
<xs:element name="ServiceCategoryList" type="tns:ServiceCategoryListType" />
<xs:element name="ServiceName" type="tns:ServiceNameType" minOccurs="0" />
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceDescription2" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceNumber" type ="tns:ServiceNumberType" />
<xs:element name="ServiceProvider" type="tns:ProviderNameType" />
<xs:element name="ServiceIconFile" type="tns:ServiceIconFileType" minOccurs="0" />
<xs:element name="ServiceSpecificExtension" type="tns:ServiceSpecificExtensionType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ServiceCategoryListType">
<xs:sequence>
<xs:element name="ServiceCategory" type="tns:ServiceCategoryType" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ServiceCategoryType">
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string" />
</xs:simpleType>
<xs:simpleType name="ServiceCategoryTypeEnumeration">
<xs:restriction base="xs:string" >
<xs:enumeration value="Network" />
<xs:enumeration value="Network.MobileBroadband" />
<xs:enumeration value="Other" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNameType">
<xs:restriction base="xs:string">
<xs:minLength value="0" />
<xs:maxLength value="200" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNumberType">
<xs:union memberTypes="tns:GUIDType xs:string" />
</xs:simpleType>
<xs:simpleType name="ProviderNameType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceDescriptionType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="1024" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceIconFileType">
<xs:restriction base="xs:string">
<xs:pattern value=".+\.ico" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="GUIDType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ServiceSpecificExtensionType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="namespace" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
ServiceInfo XML elements list
4/13/2022 • 2 minutes to read • Edit Online
This section describes the XML elements defined by the ServiceInfo XML schema. The following is a list of these
elements in the order in which they are defined in the XML schema.
ServiceInfo
ServiceCategoryList
ServiceCategory
ServiceName
ServiceDescription1
ServiceDescription2
ServiceNumber
ServiceProvider
ServiceIconFile
ServiceSpecificExtension
ServiceInfo
4/13/2022 • 2 minutes to read • Edit Online
The ServiceInfo element is the parent element of the ServiceInfo XML schema.
Usage
<ServiceInfo>
child elements
</ServiceInfo>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
ServiceIconFile Specifies the name of the service icon file in the service
metadata package.
Note
This is listed as optional in the schema. However, it is
required in order to pass validation when the package
is submitted to the Windows Dev Center Dashboard.
Parent elements
There are no parent elements.
XSD
<xs:element name="ServiceInfo" type="tns:ServiceInfoType" />
<xs:complexType name="ServiceInfoType">
<xs:sequence>
<xs:element name="ServiceCategoryList" type="tns:ServiceCategoryListType" />
<xs:element name="ServiceName" type="tns:ServiceNameType" minOccurs="0" />
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceDescription2" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceNumber" type ="tns:ServiceNumberType" />
<xs:element name="ServiceProvider" type="tns:ProviderNameType" />
<xs:element name="ServiceIconFile" type="tns:ServiceIconFileType" minOccurs="0" />
<xs:element name="ServiceSpecificExtension" type="tns:ServiceSpecificExtensionType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The ServiceInfo element must contain one instance of the ServiceCategoryList, ServiceNumber, ServiceProvider,
and ServiceSpecificExtension elements.
The ServiceInfo element is required.
ServiceCategoryList
4/13/2022 • 2 minutes to read • Edit Online
The ServiceCategoryList element specifies one or more functional categories that apply to the service. Each
functional category is specified through a ServiceCategory element.
Usage
<ServiceCategorylist>
child element
</ServiceCategorylist>
Attributes
There are no attributes.
Text value
Must contain one ServiceCategory element.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceCategoryList" type="tns:ServiceCategoryListType" />
<xs:complexType name="ServiceCategoryListType">
<xs:sequence>
<xs:element name="ServiceCategory" type="tns:ServiceCategoryType" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The following discusses the use of the ServiceCategoryList elements in a service metadata package:
The first ServiceCategory element in the ServiceCategoryList element specifies the service’s primary
functional category. The primary functional category should match how the service is advertised,
packaged, sold, and ultimately identified by users.
Because a service is defined only by its primary functional category, you should specify only one instance
of the ServiceCategory element in the ServiceCategoryList element.
The ServiceCategory for service metadata packages must be one of the following:
Network.MobileBroadband
Network.MobileBroadband.CDMA
Network.MobileBroadband.GSM
The ServiceCategoryList element is required.
ServiceCategory
4/13/2022 • 2 minutes to read • Edit Online
The ServiceCategory element specifies the functional category that applies to the service.
Usage
<ServiceCategory>
text
</ServiceCategory>
Attributes
There are no attributes.
Text value
Must contain one ServiceCategory element.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceCategory" type="tns:ServiceCategoryType" maxOccurs="unbounded" />
<xs:simpleType name="ServiceCategoryType">
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string"/>
</xs:simpleType>
<xs:simpleType name="ServiceCategoryTypeEnumeration">
<xs:restriction base="xs:string">
<xs:enumeration value="Network"/>
<xs:enumeration value="Network.MobileBroadband"/>
<xs:enumeration value="Other"/>
</xs:restriction>
</xs:simpleType>
Remarks
The following discusses the use of the ServiceCategoryList elements in a service metadata package:
The first ServiceCategory element in the ServiceCategoryList element specifies the service’s primary
functional category. The primary functional category should match how the service is advertised,
packaged, sold, and ultimately identified by users.
Because a service is defined only by its primary functional category, you should specify only one instance
of the ServiceCategory element in the ServiceCategoryList element.
The ServiceCategory for service metadata packages must be one of the following:
Network.MobileBroadband
Network.MobileBroadband.CDMA
Network.MobileBroadband.GSM
The ServiceCategory element is required.
ServiceName
4/13/2022 • 2 minutes to read • Edit Online
Usage
<ServiceName>
text
</ServiceName>
Attributes
There are no attributes.
Text value
A string that is less than 200 characters in length.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceName" type="tns:ServiceNameType" minOccurs="0" />
<xs:simpleType name="ServiceNameType">
<xs:restriction base="xs:string">
<xs:minLength value="0" />
<xs:maxLength value="200" />
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceName element is not currently used.
ServiceDescription1
4/13/2022 • 2 minutes to read • Edit Online
The ServiceDescription1 element specifies descriptive information about the service. This is applied to the
description field of the wireless wide area network (WWAN) connection profile. It is not displayed in the user
interface to the end user and should be left blank.
Usage
<ServiceDescription1>
text
</ServiceDescription1>
Attributes
There are no attributes.
Text value
A string that is less than 1024 characters in length.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0"/>
<xs:simpleType name="ServiceDescriptionType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="1024"/>
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceDescription1 element does not appear to the end user in any user interface.
The ServiceDescription1 element is optional and should be left blank.
ServiceDescription2
4/13/2022 • 2 minutes to read • Edit Online
Usage
<ServiceDescription2>
text
</ServiceDescription2>
Attributes
There are no attributes.
Text value
A string that is less than 1024 characters in length.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceDescription2" type="tns:ServiceDescriptionType" minOccurs="0"/>
<xs:simpleType name="ServiceDescriptionType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="1024"/>
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceDescription2 is not currently used.
ServiceNumber
4/13/2022 • 2 minutes to read • Edit Online
The ServiceNumber element specifies the unique self-generated GUID that represents the mobile operator. This
GUID must be present and is checked when account provisioning metadata is applied to a PC to ensure a match
with the GUID value declared in the Carrier ID identified in that file. The account provisioning metadata is
generated by the mobile broadband app or an operator website. Account provisioning metadata is described in
Account provisioning.
Usage
<ServiceNumber>
text
</ServiceNumber>
Attributes
There are no attributes.
Text value
A string of GUIDType.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceNumber" type ="tns:ServiceNumberType" />
<xs:simpleType name="ServiceNumberType">
<xs:union memberTypes="tns:GUIDType xs:string" />
</xs:simpleType>
Remarks
The ServiceNumber element is required.
ServiceProvider
4/13/2022 • 2 minutes to read • Edit Online
IMPORTANT
In Windows 10, version 1709 and later, this field has been replaced by branding through COSA. Fields in COSA for
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions of
Windows before Windows 10, version 1709, you will still create a metadata package as described in this section. For more
information about COSA, see COSA overview.
The ServiceProvider element specifies the name of the service provider. It is shown in Windows Connection
Manger to display the home provider network name. If the user is on a roaming network the roaming network
name is displayed instead.
Usage
<ServiceProvider>
text
</ServiceProvider>
Attributes
There are no attributes.
Text value
A string of up to 20 printable characters.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
<xs:simpleType name="ProviderNameType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceProvider element is not shown in Windows Connection Manager when the user is roaming.
The ServiceProvider element is required.
ServiceIconFile
4/13/2022 • 2 minutes to read • Edit Online
IMPORTANT
In Windows 10, version 1709 and later, this field has been replaced by branding through COSA. Fields in COSA for
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions of
Windows before Windows 10, Version 1709, you will still create a metadata package as described in this section. For more
information about COSA, see COSA overview.
The ServiceIconFile element specifies the name of the service icon file in the service metadata package. The
service icon file is used to display the logo of the mobile network operator (MNO) or mobile virtual network
operator (MVNO) in Windows Connection Manager.
Usage
<ServiceProvider>
text
</ServiceProvider>
Attributes
There are no attributes.
Text value
The name of an icon file with an .ICO extension.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
<xs:simpleType name="ServiceIconFileType">
<xs:restriction base="xs:string">
<xs:pattern value=".+\.ico"/>
</xs:restriction>
</xs:simpleType>
Remarks
The required icon file sizes are as follows:
256x256:32bit+Alpha(compressed) 24x24:32bit+Alpha
48x48:32bit+Alpha 24x24:8bit256
48x48:8bit256 24x24:4bit16
48x48:4bit16 16x16:32bit+Alpha
32x32:32bit+Alpha 16x16:8bit256
32x32:8bit256 16x16:4bit16
32x32:4bit16
The ServiceIconFile element is marked as optional in the schema. However, service metadata packages that are
submitted to the Windows Dev Center Dashboard without the ServiceIconFile element will be rejected.
ServiceSpecificExtension
4/13/2022 • 2 minutes to read • Edit Online
The ServiceSpecificExtension element specifies the relative location of the MobileBroadbandInfo.xml file.
Usage
<ServiceSpecificExtension
name = “xs:anyURI”>
text
</ServiceSpecificExtension>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Text value
The name of the XML file that contains the MobileBroadbandInfo schema.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ServiceSpecificExtension" type="tns:ServiceSpecificExtensionType" minOccurs="0" />
<xs:complexType name="ServiceSpecificExtensionType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="namespace" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
The ServiceSpecificExtension element is required.
GUIDType (ServiceInfo)
4/13/2022 • 2 minutes to read • Edit Online
<xs:simpleType name="GUIDType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
Patterns
The GUIDType simple type is a xs:string that is restricted by the following pattern:
[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
ServiceInfo XML Example
4/13/2022 • 2 minutes to read • Edit Online
The following XML document uses the ServiceInfo XML schema to specify the attributes of the Contoso Wireless
service:
<DeviceInfo xmls="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo">
<ServiceCategoryList>
<ServiceCategory>Network.MobileBroadband </ServiceCategory>
</ServiceCategoryList>
<ServiceName> </ServiceName>
<ServiceDescription1>Fabrikam Wireless 3G network</ServiceDescription1>
<ServiceDescription2></ServiceDescription2>
<ServiceNumber>D4A5C6D5-8135-4A0D-9B9D-016F5D7D9F45 </ServiceNumber>
<ServiceProvider>Contoso Wireless</ServiceProvider>
<ServiceIcon>Contoso.ico</ServiceIcon>
<ServiceSpecificExtension
namespace="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo">MobileBroadbandI
nfo.xml</ServiceSpecificExtension>
</ServiceInfo>
SoftwareInfo XML schema overview
4/13/2022 • 2 minutes to read • Edit Online
A metadata package contains one SoftwareInfo.xml document, which contains information that the operating
system downloads a UWP app. This information results in privileged access for apps.
The data within the Softwareinfo.xml document is formatted based on the SoftwareInfo XML Schema, which is
described in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the SoftwareInfo XML schema, see SoftwareInfo XML Schema Definition.
For information about the elements that are defined by the SoftwareInfo XML schema, see SoftwareInfo XML
Schema Definition.
For an example of XML data in the format that is defined by the SoftwareInfo XML schema, see SoftwareInfo
XML Example.
SoftwareInfo XML Schema Definition
4/13/2022 • 2 minutes to read • Edit Online
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
<xs:minLength value="3"/>
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
<xs:maxLength value="8192"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DistinguishedNameType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9]
[0-9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9]
[0-9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ApplicationType">
<xs:sequence>
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0"
/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="Id" type="tns:ApplicationIdType" use="required"/>
</xs:complexType>
<xs:simpleType name="ApplicationIdType">
<xs:restriction base="tns:AsciiWindowsIdType">
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="PackageForPrivilegedApplications">
<xs:sequence>
<xs:element name="Identity" type="tns:IdentityForPrivilegedApplicationsType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="IdentityForPrivilegedApplicationsType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required"/>
<xs:attribute name="Publisher" type="tns:PublisherType" use="required"/>
<xs:attribute name="AccessCustomDriver" type="xs:boolean" />
</xs:complexType>
<xs:simpleType name="AsciiIdentifierType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^_ ]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NonEmptyStringType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiWindowsIdType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="([A-Za-z][A-Za-z0-9]*)(\.[A-Za-z][A-Za-z0-9]*)*"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="UnicodeIdentifierType">
<xs:restriction base="tns:UnicodeIdentifierCharSetType" />
</xs:simpleType>
<xs:simpleType name="UnicodeIdentifierCharSetType">
<xs:restriction base="tns:AllowedUnicodeCharSetType">
<xs:pattern value="[^!#$%'()\*\+,/:;=\?@\[\\\]^_`\|]+" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AllowedUnicodeCharSetType">
<xs:restriction base="tns:UnicodeNoPrivateUseOrNonCharacterCodePointsType">
<xs:pattern value="[^"&<>\u0000-\u0020\u007F\u0080-\u009F\u00A0\u00AD\u0340-
\u0341\u034F\u06DD\u070F\u1680\u1806\u180B-\u180E\u2000-\u200F\u2028-\u202F\u205F\u2060-\u2063\u206A-
\u206F\u2FF0-\u2FFB\u3000\uD800-\uDFFF\uFEFF\p{IsVariationSelectors}]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="UnicodeNoPrivateUseOrNonCharacterCodePointsType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="[^\uE000-\uF8FF\uFDD0-\uFDEF\uFFF9-\uFFFF\p{IsPrivateUse}]+"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
<?xml version="1.0" encoding ="UTF-8" ?>
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
blockDefault="#all">
<xs:complexType name="ServiceInfoType">
<xs:sequence>
<xs:element name="ServiceCategoryList" type="tns:ServiceCategoryListType" />
<xs:element name="ServiceName" type="tns:ServiceNameType" minOccurs="0" />
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceDescription2" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceNumber" type ="tns:ServiceNumberType" />
<xs:element name="ServiceProvider" type="tns:ProviderNameType" />
<xs:element name="ServiceIconFile" type="tns:ServiceIconFileType" minOccurs="0" />
<xs:element name="ServiceSpecificExtension" type="tns:ServiceSpecificExtensionType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ServiceCategoryListType">
<xs:sequence>
<xs:element name="ServiceCategory" type="tns:ServiceCategoryType" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ServiceCategoryType">
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string" />
</xs:simpleType>
<xs:simpleType name="ServiceCategoryTypeEnumeration">
<xs:restriction base="xs:string" >
<xs:enumeration value="Network" />
<xs:enumeration value="Network.MobileBroadband" />
<xs:enumeration value="Other" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNameType">
<xs:restriction base="xs:string">
<xs:minLength value="0" />
<xs:maxLength value="200" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNumberType">
<xs:union memberTypes="tns:GUIDType xs:string" />
</xs:simpleType>
<xs:simpleType name="ProviderNameType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="20" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceDescriptionType">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
<xs:maxLength value="1024" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceIconFileType">
<xs:restriction base="xs:string">
<xs:restriction base="xs:string">
<xs:pattern value=".+\.ico" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="GUIDType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ServiceSpecificExtensionType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="namespace" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
SoftwareInfo XML elements list
4/13/2022 • 2 minutes to read • Edit Online
This section describes the XML elements defined by the SoftwareInfo XML schema. The following is a list of
these elements in the order in which they are defined in the XML schema.
SoftwareInfo
DeviceCompanionApplications
Package
Identity
Applications
Application
DeviceNotificationHandlers
DeviceNotificationHandler
PrivilegedApplications
Package
Identity
SoftwareInfo
4/13/2022 • 2 minutes to read • Edit Online
The SoftwareInfo element is the parent element of the SoftwareInfo XML schema.
Usage
<SoftwareInfo>
child elements
</SoftwareInfo>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
There are no parent elements.
XSD
<xs:element name="SoftwareInfo" type="tns:SoftwareInfoType" />
<xs:complexType name="SoftwareInfoType">
<xs:choice>
<xs:sequence>
<xs:element name="DeviceCompanionApplications" type="tns:DeviceCompanionApplicationsType" />
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" />
</xs:choice>
</xs:complexType>
Remarks
The SoftwareInfo element is required.
DeviceCompanionApplications
4/13/2022 • 2 minutes to read • Edit Online
The DeviceCompanionApplications element specifies the app that will be downloaded when the operator’s
mobile broadband hardware is detected on the PC.
Usage
<DeviceCompanionApplications>
child elements
</DeviceCompanionApplications>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Package Specifies the package that will be used for the Microsoft
Store device app.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="DeviceCompanionApplications" type="tns:DeviceCompanionApplicationsType" />
<xs:complexType name="DeviceCompanionApplicationsType">
<xs:sequence>
<xs:element name="Package" type="tns:PackageType" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
When you specify the DeviceCompanionApplications element, the specified app will be downloaded
when Windows detects the operator’s mobile broadband hardware.
The structure for the package Identity and Application element are identical with the application manifest
structure.
For Windows 8, Windows 8.1, and Windows 10, you can specify only one package and one application ID.
The second package or application ID will be ignored if you specify it.
The DeviceCompanionApplications element is optional.
Package (SoftwareInfo)
4/13/2022 • 2 minutes to read • Edit Online
The Package element specifies the app that will be downloaded when the operator’s mobile broadband
hardware is detected on the PC.
Usage
<Package>
child elements
</Package>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Package" type="tns:PackageType" maxOccurs="unbounded" />
<xs:complexType name="PackageType">
<xs:sequence>
<xs:element name="Identity" type="tns:IdentityType" />
<xs:element name="Applications" type="tns:ApplicationsType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The Package element is optional.
Identity (SoftwareInfo)
4/13/2022 • 2 minutes to read • Edit Online
The Identity element specifies the publisher identity and application manifest name of the app.
Usage
<Identity Name=”tns:AsciiIdentifierType” Publisher=”tns:DistinguishedNameType” />
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Identity" type="tns:IdentityType" />
<xs:complexType name="IdentityType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required"/>
<xs:attribute name="Publisher" type="tns:PublisherType" use="required"/>
</xs:complexType>
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
<xs:minLength value="3"/>
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
<xs:maxLength value="8192"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiIdentifierType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^_ ]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DistinguishedNameType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9][0-
9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-
9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NonEmptyStringType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AllowedAsciiCharSetType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="[-_. A-Za-z0-9]+"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Identity element is optional.
Applications
4/13/2022 • 2 minutes to read • Edit Online
The Applications element specifies the apps that are associated with the Mobile Broadband hardware device.
Usage
<Applications>
Child element
</Applications>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Applications" type="tns:ApplicationsType" />
<xs:complexType name="ApplicationsType">
<xs:sequence>
<xs:element name="Application" type="tns:ApplicationType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The Applications element is optional.
Application (SoftwareInfo)
4/13/2022 • 2 minutes to read • Edit Online
Usage
<Application Id=”tns:ApplicationIdType”>
Child element
</Application>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Application" type="tns:ApplicationType"/>
<xs:complexType name="ApplicationType">
<xs:sequence>
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="Id" type="tns:ApplicationIdType" use="required"/>
</xs:complexType>
Remarks
The Application element is optional.
DeviceNotificationHandlers
4/13/2022 • 2 minutes to read • Edit Online
Usage
<DeviceNotificationHandlers>
Child element
</DeviceNotificationHandlers>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0" />
<xs:complexType name="DeviceNotificationHandlersType">
<xs:sequence>
<xs:element name="DeviceNotificationHandler" type="tns:DeviceNotificationHandlerType"
maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The DeviceNotificationHandlers element is optional.
DeviceNotificationHandler
4/13/2022 • 2 minutes to read • Edit Online
The DeviceNotificationHandler element specifies a device notification handler. A device notification handler
allows you to run code in response to events, such as mobile network operator administrative SMS or USSD
notifications, even if the Microsoft Store app is not running. For more information about implementing a
notification handler, see the Mobile Operator Notifications white paper.
Usage
<DeviceNotificationHandler EventID=”xs:string” EventAsset=”xs:string”/>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="DeviceNotificationHandler" type="tns:DeviceNotificationHandlerType" maxOccurs="unbounded"
/>
<xs:complexType name="DeviceNotificationHandlerType">
<xs:attribute name="EventID" type="xs:string" use="required"/>
<xs:attribute name="EventAsset" type="xs:string" use="required"/>
</xs:complexType>
Remarks
When you specify the DeviceNotificationHandler in the Application element, the system calls the event
handler and invokes the event when the device changes to the state.
The EventID attribute is the SMSEventHandler for the SMS device case.
The EventAsset attribute is the same value that you specify in the app manifest as an extension of
Windows.BackgroundTasks.
The DeviceNotificationHandler element is optional.
PrivilegedApplications
4/13/2022 • 2 minutes to read • Edit Online
The PrivilegedApplications element specifies the app that will be allowed to access privileged Mobile Broadband
interfaces.
Usage
<PrivilegedApplications>
Child elements
</PrivilegedApplications>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" minOccurs="0" />
<xs:complexType name="PrivilegedApplicationsType">
<xs:choice>
<xs:element name="AnyApplication" type="tns:AnyApplicationType" />
<xs:element name="Package" type="tns:PackageForPrivilegedApplications" maxOccurs="unbounded" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:choice>
</xs:complexType>
Remarks
The PrivilegedApplications element allows a specified app to access the Mobile Broadband and SMS APIs
with privileged access rights.
The structure for the package Identity is identical with the <Identity> element in the application manifest
structure. You should copy the elements from the application manifest.
To specify multiple packages, list multiple Package elements in the PrivilegedApplications element.
The Package Name, Publisher, and Application ID must match the information in package.appxmanifest
for the Microsoft Store app. The publisher also must match the publisher certificate that is installed on the
PC.
For the Microsoft Store app that is listed under the DeviceCompanionApplications element to have access
to privileged Mobile Broadband interfaces including SMS, that app also must be specified under the
PrivilegedApplications element.
When you are submitting your service metadata package to the Windows Dev Center Dashboard, you
cannot declare more than 2 privileged apps. One of apps must be the app ID for the Microsoft Store
device app that will be automatically downloaded. The second privileged app is not automatically
downloaded, but will access to the privileged Mobile Broadband APIs if the app is installed.
The PrivilegedApplications element is optional.
Package (SoftwareInfo - priviliged applications)
4/13/2022 • 2 minutes to read • Edit Online
The Package element specifies an app that should have access to the privileged Mobile Broadband interfaces.
Usage
<Package>
child element
</Package>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Package" type="tns:PackageForPrivilegedApplications" maxOccurs="unbounded" />
<xs:complexType name="PackageForPrivilegedApplications">
<xs:sequence>
<xs:element name="Identity" type="tns:IdentityForPrivilegedApplicationsType" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The Package element is optional.
Identity (SoftwareInfo - priviliged applications)
4/13/2022 • 2 minutes to read • Edit Online
The Identity element specifies the publisher identity and application manifest name of the app.
Usage
<Identity Name=”tns:AsciiIdentifierType” Publisher=”tns:DistinguishedNameType”
AccessCustomDriver=”xs:boolean” />
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Identity" type="tns:IdentityForPrivilegedApplicationsType" />
<xs:complexType name="IdentityForPrivilegedApplicationsType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required"/>
<xs:attribute name="Publisher" type="tns:PublisherType" use="required"/>
<xs:attribute name="AccessCustomDriver" type="xs:boolean" />
</xs:complexType>
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
<xs:minLength value="3"/>
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
<xs:maxLength value="8192"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiIdentifierType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^_ ]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DistinguishedNameType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9][0-
9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-
9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NonEmptyStringType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AllowedAsciiCharSetType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="[-_. A-Za-z0-9]+"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Identity element is optional.
SoftwareInfo XML Example
4/13/2022 • 2 minutes to read • Edit Online
The following XML document uses the ServiceInfo XML schema to specify the attributes of the Contoso Wireless
service:
<SoftwareInfo xmlns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo">
<DeviceCompanionApplications>
<Package>
<Identity Name="64022CONTOSO.ContosoDeviceApp" Publisher="CN=05558413-FFF6-4AA5-8176-AD43036533FA" />
<Applications>
<Application Id="DeviceAppForPrinters">
<DeviceNotificationHandlers>
<DeviceNotificationHandler EventID="NotificationHandler" EventAsset="Fabrikam.OperatorApp.
NotificationHandler" />
</DeviceNotificationHandlers>
</Application>
</Applications>
</Package>
</DeviceCompanionApplications>
<PrivilegedApplications>
<Package>
<Identity Name="64022CONTOSO.ContosoDeviceApp" Publisher="CN=05558413-FFF6-4AA5-8176-AD43036533FA"
AccessCustomDriver="false" />
</Package>
</PrivilegedApplications>
</SoftwareInfo>
WindowsInfo XML schema overview
4/13/2022 • 2 minutes to read • Edit Online
A metadata package contains one WindowsInfo.xml document. This contains information that the operating
system uses to define display actions for the service specified within the metadata package.
The data within the Windowsinfo.xml document is formatted based on the WindowsInfo XML schema, which is
described in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the WindowsInfo XML schema, see WindowsInfo XML Schema Definition.
For information about the elements that are defined by the WindowsInfo XML schema, see WindowsInfo XML
Elements.
For an example of XML data in the format that is defined by the WindowsInfo XML schema, see WindowsInfo
XML Example.
WindowsInfo XML Schema Definition
4/13/2022 • 2 minutes to read • Edit Online
http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/"
xmlns:tns="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/"
xmlns:v2="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" blockDefault="#all">
<xs:complexType name="WindowsInfoType">
<xs:sequence>
<xs:element name="ShowDeviceInDisconnectedState" type="xs:boolean" default="false" />
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:schema>
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" blockDefault="#all">
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
<xs:minLength value="3"/>
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiIdentifierType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^_ ]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
<xs:maxLength value="8192"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DistinguishedNameType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9]
[0-9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9]
[0-9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AutoplayTypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="Device" />
<xs:enumeration value="Content" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ApplicationIdType">
<xs:restriction base="tns:AsciiWindowsIdType">
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiWindowsIdType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="([A-Za-z][A-Za-z0-9]*)(\.[A-Za-z][A-Za-z0-9]*)*"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NonEmptyStringType">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="32767"/>
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
WindowsInfo XML elements list
4/13/2022 • 2 minutes to read • Edit Online
This section describes the XML elements defined by the WindowsInfo XML schema. The following is a list of
these elements in the order in which they are defined in the XML schema.
WindowsInfo
ShowDeviceInDisconnectedState
LaunchDeviceStageOnDeviceConnect
LaunchDeviceStageFromExplorer
LaunchApplicationOnDeviceConnect
AutoplayHandler
PackageIdentity
Application
Verb
AutoplayType
EnableAutoPlayForRegisteredApps
DesktopAutoplayHandler
WindowsInfo
4/13/2022 • 2 minutes to read • Edit Online
The WindowsInfo element is the parent element of the WindowsInfo XML schema.
Usage
<WindowsInfo>
child elements
</WindowsInfo>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
There are no parent elements.
XSD
<xs:element name="WindowsInfo" type="tns:WindowsInfoType" />
<xs:complexType name="WindowsInfoType">
<xs:sequence>
<xs:element name="ShowDeviceInDisconnectedState" type="xs:boolean" default="false" />
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" minOccurs="0" />
<xs:element ref="v2:LaunchApplicationOnDeviceConnect" minOccurs="0" />
<xs:element ref="v2:WindowsHardwareLogoCertified" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The WindowsInfo element is required.
ShowDeviceInDisconnectedState
4/13/2022 • 2 minutes to read • Edit Online
The ShowDeviceInDisconnectedState element should be set to false because it does not apply to service
metadata packages in Windows 8, Windows 8.1, and Windows 10.
Usage
<ShowDeviceInDisconnectedState>
text
</ShowDeviceInDisconnectedState>
Attributes
There are no attributes.
Text value
Should be set to false because it does not apply to service metadata packages in Windows 8, Windows 8.1, and
Windows 10.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="ShowDeviceInDisconnectedState" type="xs:boolean" default="false" />
Remarks
The ShowDeviceInDisconnectedState element is required.
LaunchDeviceStageOnDeviceConnect
4/13/2022 • 2 minutes to read • Edit Online
The LaunchDeviceStageOnDeviceConnect element should be set to false because it does not apply to service
metadata packages in Windows 8, Windows 8.1, and Windows 10.
Usage
<LaunchDeviceStageOnDeviceConnect>
text
</LaunchDeviceStageOnDeviceConnect>
Attributes
There are no attributes.
Text value
Should be set to false because it does not apply to service metadata packages in Windows 8, Windows 8.1, and
Windows 10.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" />
Remarks
The LaunchDeviceStageOnDeviceConnect element is optional.
LaunchDeviceStageFromExplorer
4/13/2022 • 2 minutes to read • Edit Online
The LaunchDeviceStageFromExplorer element should be set to false because it does not apply to service
metadata packages in Windows 8, Windows 8.1, and Windows 10.
Usage
<LaunchDeviceStageFromExplorer>
text
</LaunchDeviceStageFromExplorer>
Attributes
There are no attributes.
Text value
Should be set to false because it does not apply to service metadata packages in Windows 8, Windows 8.1, and
Windows 10.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" />
Remarks
The LaunchDeviceStageFromExplorer element is optional.
LaunchApplicationOnDeviceConnect
4/13/2022 • 2 minutes to read • Edit Online
The LaunchApplicationOnDeviceConnect element specifies an app that should appear as the recommended
AutoPlay action when a user plugs in the device.
Usage
<LaunchApplicationOnDeviceConnect>
child elements
</LaunchApplicationOnDeviceConnect>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="LaunchApplicationOnDeviceConnect" type ="tns:LaunchApplicationOnDeviceConnectType" />
<xs:complexType name="LaunchApplicationOnDeviceConnectType">
<xs:choice>
<xs:element name="AutoplayHandler" type="tns:AutoplayHandlerType" />
<xs:element name="DesktopAutoplayHandler" type="xs:string" />
<xs:any namespace="##other" processContents="lax" />
</xs:choice>
</xs:complexType>
Remarks
You must specify either a UWP device app or a desktop app. Use AutoplayHandler if you will specify a UWP
device app, and use DesktopAutoplayHandler if you specify a desktop application.
The LaunchApplicationOnDeviceConnect element is optional.
AutoplayHandler
4/13/2022 • 2 minutes to read • Edit Online
The AutoplayHandler element specifies a UWP device app that should appear as the recommended AutoPlay
action when a user plugs in a device.
Usage
<AutoplayHandler>
child elements
</AutoplayHandler>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="AutoplayHandler" type="tns:AutoplayHandlerType" />
<xs:complexType name="AutoplayHandlerType">
<xs:sequence>
<xs:element name="PackageIdentity" type="tns:PackageIdentityType" />
<xs:element name="Application" type="tns:ApplicationType" />
<xs:element name="Verb" type="tns:VerbType" />
<xs:element name="AutoplayType" type="tns:AutoplayTypeType" />
<xs:element name="EnableAutoPlayForRegisteredApps" type ="xs:boolean" default="false" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The structure for the PackageIdentity and Application elements are identical with the Application Manifest
structure, so copy the elements from the application's manifest.
In addition to including the AutoplayHandler element in the device metadata, the specified UWP device
app must also register for the AutoPlay event by adding a Declaration in its application manifest for the
event. AutoPlay recognizes the declaration for the app and then includes it in the list of possible actions
that a user can take to respond to that event.
Only the package listed in the DeviceCompanionApplications value in the SoftwareInfo.xml file will be
downloaded as part of the device installation. If the LaunchApplicationOnDeviceConnect element value is
from a different package, Windows does not know whether it will actually be on the user’s device. If the
recommended application is not on the user’s device, users will not be presented with the choice.
Even if the application is the same as the DeviceCompanionApplications entry, it may not always appear
in the AutoPlay list. If the user is not connected to the Internet or otherwise fails to download the
companion application, it will not appear in the list. However, when the user gets the application, they will
be presented with a “New Option Available” AutoPlay dialog box the next time they connect their device.
The AutoplayHandler element is optional.
PackageIdentity
4/13/2022 • 2 minutes to read • Edit Online
The PackageIdentity element specifies a UWP device app that should appear as the recommended AutoPlay
action when a user plugs in a device.
Usage
<PackageIdentity Name=”tns:PackageNameType” Publisher=”tns:PublisherType” />
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="PackageIdentity" type="tns:PackageIdentityType" />
<xs:complexType name="PackageIdentityType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required" />
<xs:attribute name="Publisher" type="tns:PublisherType" use="required" />
</xs:complexType>
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
<xs:minLength value="3"/>
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
<xs:maxLength value="8192"/>
</xs:restriction>
</xs:simpleType>
Remarks
Copy the Name and Publisher attributes from the application manifest's <Identity> element after the app has
been associated with the Microsoft Store, because the process of associating your app will update the app
manifest.
Here is an example of how the <Identity> element may look inside an app manifest.
Usage
<Application Id=”tns:ApplicationIdType” />
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Application" type="tns:ApplicationType" />
<xs:complexType name="ApplicationType">
<xs:attribute name="Id" type="tns:ApplicationIdType" use="required"/>
</xs:complexType>
<xs:simpleType name="ApplicationIdType">
<xs:restriction base="tns:AsciiWindowsIdType">
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
Remarks
The structure for the Application element correspond to the structure of the <Application> element in an app
manifest. Copy the value of the Id value from the Id attribute in the app manifest.
Here is an example of how the <Applications> element may be structured inside an app manifest:
<Applications>
<Application Id="DeviceAppForPrinters" Executable="$targetnametoken$.exe"
EntryPoint="DeviceAppForPrinters.App">
</Application>
</Applications>
The Verb element specifies the Verb that the application registers.
Usage
<Verb />
Attributes
There are no attributes.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="Verb" type="tns:VerbType" />
<xs:simpleType name="VerbType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^ ]+"/>
<xs:maxLength value="64"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Verb element is optional.
AutoplayType
4/13/2022 • 2 minutes to read • Edit Online
The AutoplayType element specifies whether the AutoPlay event is a device event or a content event. AutoPlay
determines the type of device and raises either a Device event for non-volume devices, or a Content event for
volume devices.
Usage
<AutoplayType>
type
</AutoplayType>
Attributes
There are no attributes.
Text value
A string that has either the value "Device" or the value "Content".
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="AutoplayType" type="tns:AutoplayTypeType" />
<xs:simpleType name="AutoplayTypeType">
<xs:restriction base="xs:string">
<xs:enumeration value="Device" />
<xs:enumeration value="Content" />
</xs:restriction>
</xs:simpleType>
Remarks
The AutoplayType element is optional.
EnableAutoPlayForRegisteredApps
4/13/2022 • 2 minutes to read • Edit Online
The EnableAutoPlayForRegisteredApps element specifies whether AutoPlay is enabled for registered apps.
Usage
<EnableAutoPlayForRegisteredApps>
text
</EnableAutoPlayForRegisteredApps>
Attributes
There are no attributes.
Text value
A Boolean value of either “true” or “false”.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="EnableAutoPlayForRegisteredApps" type ="xs:boolean" default="false"/>
Remarks
This element is only applicable on Windows 8.1 and Windows 10.
The EnableAutoPlayForRegisteredApps element is optional.
DesktopAutoplayHandler
4/13/2022 • 2 minutes to read • Edit Online
The DesktopAutoplayHandler element specifies a desktop app that should appear as the recommended
AutoPlay action when the device is connected and no default action is set. The AutoPlay event is raised
whenever a user plugs in a device.
Usage
<DesktopAutoplayHandler>
text
</DesktopAutoplayHandler>
Attributes
There are no attributes.
Text value
String indicating the desktop app that handles the AutoPlay event.
Child elements
There are no child elements.
Parent elements
EL EM EN T DESC RIP T IO N
XSD
<xs:element name="DesktopAutoplayHandler" type="xs:string" />
Remarks
You specify the desktop AutoPlay Handler string in the DesktopAutoplayHandler element when you set the
desktop app. You can retrieve the string from the handler subkey name that is registered under the following
registry key:
HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\AutoplayHandlers\Handlers
The following XML document uses the WindowsInfo XML schema to specify the display actions for the service
that is specified within a metadata package:
To generate hardware ID values for your service metadata package, you can use the MBIDGenerator.exe
command-line tool, which is part of the SDK in Windows 8.1 and Windows 10.
Note In Windows 8 MBIDGenerator.exe was included in the WDK.
Input
MBIDGenerator.exe accepts the following parameters:
Note The Test parameter provides non-hashed output and should not be used for generating hardware IDs for
submission to the Windows Dev Center Dashboard.
Output
The output from the MBIDGenerator.exe is through a standard command-line output display. Optionally, you can
specify a path and file name for the output file. Errors are always reported back to the command prompt.
The output values appear in the following way:
<HardwareIDList>
<HardwareID>MBAE:0:hashednumber1</HardwareID>
<HardwareID>MBAE:0:hashednumber2</HardwareID>
<HardwareID>MBAE:0:hashednumber3</HardwareID>
</HardwareIDList>
You can take the output from MBIDGenerator.exe and insert it into the PackageInfo XML schema of your service
metadata package.
Mobile Plans overview
4/13/2022 • 3 minutes to read • Edit Online
Purpose
Mobile Plans is an application in Windows 10 that helps end users to connect their Windows device to cellular
networks through mobile operators. The purpose of Mobile Plans is to:
Provide a consistent and simplified user experience for activation of cellular-enabled PCs.
Enable a new channel for cellular activation through adoption of eSIM
Increase adoption of cellular services on Windows PCs through a direct relationship between customers and
mobile operators
Mobile Plans is supported in Windows 10, version 1803 and later.
Customer journey
The typical Mobile Plans customer journey is composed of the following steps:
ST EP DESC RIP T IO N
Discovery The user sees one of several entry points in the Windows UI
and launches the Mobile Plans app. There are multiple entry
points available in the Windows Shell that are tailored to
various scenarios.
Browse & Welcome After the Mobile Plans app launches, the user chooses their
mobile operator and sees the operator Gateway page. The
Gateway page invokes the mobile operator web portal which
hosts the next step. Note that some entry points take the
user directly to the operator Gateway page.
Activation & Checkout The mobile operator web portal walks the user through sign
in, activation and checkout
Usage The user enjoys the benefits of an always connected PC, and
is able to see available balance directly in the Windows UI.
They can easily return to the mobile operator web portal to
manage their account and purchase additional data as
needed.
User experience
The following sections illustrate the Mobile Plans user experience.
Launching the app
The Mobile Plans app can be launched from a number of different entry points. The most common entry point is
the network flyout, as this is where users typically manage their active network interfaces in Windows 10. The
cellular interface can be expanded to show status of the cellular network. In the example below, the device has
no SIM profile activated, so the user sees a call to action to “Connect with a data plan.” Selecting this link will
launch the Mobile Plans app.
See the Mobile Plans account management topic for more details on behavior of the network flyout.
The app can also be launched from a toast notification. Selecting the “Get connected” button will launch the
Mobile Plans app.
See the Mobile Plans toast notifications topic for more details on the behavior of toast notifications.
The Mobile Plans app can also be launched from the Settings app, or from the Start menu.
Select provider page
Once the app has launched, the user has the option to choose their mobile operator. The app displays a list of
available mobile operators based on the user’s current location.
See the Mobile Plans operator catalog topic for more information on this page.
This page provides an overview of the major components of the Mobile Plans system architecture. Together,
these comprise the Mobile Plans program. Not every mobile operator deployment will require every
component listed here.
The Mobile Plans system architecture made up of the following 5 major components:
Mobile Plans App
This is the Universal Windows Platform (UWP) app that is preinstalled by Microsoft on all cellular-enabled
Windows 10 devices. The Mobile Plans app is the primary client environment running on the user's device for
hosting the end user experience. The Mobile Plans app can also run in the background to trigger certain events
(e.g. showing a toast notification).
Mobile Plans Service
The Mobile Plans service is the cloud-based service layer which provides data to the Mobile Plans app. It also
provides an authenticated interface to the Mobile Operator API.
Mobile Operator Web Portal
This is the web-based runtime environment hosted by the mobile operator. The mobile operator web portal is
experienced by the user via web navigation, and is rendered in situ within the Mobile Plans app.
Mobile Operator API
This is the programmatic interface hosted by the mobile operator for exposing user data to the Mobile Plans,
which can be fetched at runtime to update content presented to the user. An example of user data fetched at
runtime would be a user's prepaid balance.
Mobile Operator SM -DP+
This is the service responsible for creation and delivery of a mobile operator's eSIM profile to the Windows 10
device.
Functional overview
The following diagram shows a high-level overview of how the components described above are used in a
typical flow to successfully activate a subscription and install an eSIM profile. Note that other flows are possible
as well.
1. The Mobile Plans app is launched on the Windows 10 device, and retrieves basic functional data from the
Mobile Plans service.
2. The Mobile Plans app invokes the mobile operator web portal, and passes relevant parameters which can be
used by the portal to determine which user experience to present.
3. Upon completion of the activation flow within the mobile operator web portal, the mobile operator requests
an eSIM profile from the SM-DP+ server. The corresponding eSIM activation code is returned to the mobile
operator web portal.
4. The mobile operator web portal returns the eSIM profile activation code to the Mobile Plans app.
5. The Mobile Plans app passes the activation code to the Windows LPA, which contacts the SM-DP+ server to
retrieve the eSIM profile.
6. The eSIM profile is downloaded and installed to the Windows 10 device eSIM, and is activated. Upon
activation, the Windows 10 device registers on the mobile operator network.
7. The user opens the Windows network flyout, which invokes a request to the Mobile Plans service to fetch the
available balance.
8. The Mobile Plans service makes a Get Balance request to the Mobile Operator API, which returns the
available balance to be displayed to the user.
Mobile Plans scenarios
4/13/2022 • 3 minutes to read • Edit Online
Overview
This topic provides guidance about most common scenarios that mobile operators will enable with Mobile
Plans. Note that this is not an exhaustive list of supported scenarios. It is probable that your specific use case
could be achieved via a combination of solutions. Please speak with your Microsoft contact to discuss your
requirements further.
Cancelling a transaction
This section describes the callback method used to notify the Mobile Plans app when a transaction is cancelled
while the user is browsing the mobile operator web portal. This applies to all the previous scenarios in this topic.
Implement the callback method for canceling purchase flow.
Mobile Plans operator catalog
4/13/2022 • 2 minutes to read • Edit Online
Overview
The Mobile Plans app enables users to see and choose from a list of mobile operators. This article defines the
principles applied in the display of mobile operators on the Select Providers page.
NOTE
The Select Providers page is only available on eSIM-enabled Windows 10 PCs. Since legacy physical UICCs do not allow
the mobile operator's SIM profile to be changed, the Select Provider page is not available when there is no active eSIM on
the device.
Device filtering
If a device (including the modem and/or eSIM hardware or firwmare) is found to be incompatible with a
mobile operator's nework, the mobile operator can request to be filtered from the list of mobile operators
shown on that device. This is to prevent an end user from attempting to acquire a data plan from an operator
which cannot be used on their device. The make and model of the device (as found in the Windows System
Info dialog), or the eID of the eSIM, must be supplied by the mobile operator to enable the filtering.
Mobile Plans gateway page
4/13/2022 • 4 minutes to read • Edit Online
Overview
The Mobile Plans app hosts a Gateway page for every mobile operator enabled in the catalog. The Gateway
page is shown to the end user as part of the Welcome step. It contains basic brand elements for the mobile
operator, as well as several links and a privacy disclaimer. The Gateway page also includes a button to invoke the
mobile operator web portal.
{ // Root object
"promotionTemplates": [
{ // PromotionTemplate
"id": 0,
"backgroundColor": "0x000000FF", // Black
"bodyFontColor": "0xFFFFFFFF", // White
"bodyText": "Stay connected from virtually anywhere.",
"buttonColor": "0x00B0F0FF", // Light Blue
"buttonFontColor": "0xFFFFFFFF", // White
"buttonText": "Get started",
"hyperlinkFontColor": "0x00B0F0FF", //Light Blue
"images": [
{ // Image
"uri": "https://picsum.photos/id/1/740/480",
"width": 740,
"height": 480,
}
]
}
]
}
The following table describes each JSON element in the previous example.
NOTE
If the device does not have an active profile for the mobile operator, the request will not be made and the template ID "0"
will be used by default.
The Get Offers request returns the template ID to be shown to the user.
GET https://{offerUri}sims/{simmri}/offers?limit=1&imei=1234
{offerUri} is the OfferUri value onboarded as part of the mobile operator's service configuration.
The endpoint has two query parameters:
limit, which is required and specifies the number of offers to return.
imei, which is optional and specifies the client’s IMEI.
The response is a JSON object with a single property named offers that contains a list of offers. The number of
offers in this list is at most limit from the request. Each offer in this list is an object with a single property
gatewayId, which must identify an existing gateway in the mobile operator’s service configuration.
The following is an example interaction using this endpoint:
GET https://moendpoint.com/v1/sims/iccid:8988247000100003319/offers?limit=1&imei=1234
X-MS-DM-TransactionId: "MSFT-12345678-1234-1234-1234-123456789abc"
HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: "MSFT-12345678-1234-1234-1234-123456789abc"
{
"offers" : [
{
"gatewayId": "0"
}
]
}
Overview
This topic describes the web portal that enables mobile operators to provide connectivity solutions directly to
Windows users through a curated web experience hosted in the Mobile Plans app. Mobile operators must create
their web experiences following these design principles to ensure users have a high quality experience while
navigating their portal. The mobile operator web portal is used for all scenarios supported in the Mobile Plans
solution and is hence one of the most important components in the program.
For more information about web portal flow and reference design, see Web portal flow and reference design.
MyWebView.ScriptNotify += MyWebView_ScriptNotify;
allowedUris.AddRange(AllowedNotifyUris);
MyWebView.AllowedScriptNotifyUris = allowedUris;
MyWebView.Navigate(“https://moportal.com?
market=US&location=US&transactionId=%2F7RBTuSJt02OZbX8.4&eid=89033023422130000000000199055797&imei=001102000
315468&iccids=8988247000101867183,8988247000103824828”);
In order to provide backwards compatibility with app updates, the portal must disregard any additional
parameters that might also be passed in the requst. This ensures flexibility and ability to introduce new features
in the app without disrupting the mobile operator's integration.
The following table describes the launch parameters available for eSIM.
The user’s language preference is sent using the Accept-Language header, described in the following table.
MyWebView.Navigate(“https://moportal.com?
iccid=8988247000100003319&imei=001102000311608&market=us&transactionId=waoigFfX00yGH3Vb.1&location=us”);
The following table describes the launch parameters available for a physical SIM.
The user’s language preference is sent using the Accept-Language header, described in the following table.
H EA DER N A M E DESC RIP T IO N EXA M P L E
The web portal experience must meet all applicable legal and Required
regulatory requirements in the countries offered. Any
content displayed in the web portal must comply with all
applicable laws.
Security
P O L IC Y REQ UIRED O R REC O M M EN DED
The web portal experience must not deliver or install any 3rd Required
party-owned or branded apps or modules.
The portal URI and all requests or notifications sent to and Required
from the web portal must use the secure HTTPS protocol.
All web portal resources and references must use the secure Required
HTTPS protocol.
Advertising
P O L IC Y REQ UIRED O R REC O M M EN DED
The web portal must not display, or make available for Required
download, any advertisements, sponsored content, videos,
sound files, animations, or otherwise large media files or
images.
Capabilities
P O L IC Y REQ UIRED O R REC O M M EN DED
Once invoked, the web portal must have and retain user Required
focus until either:
The activation flow has completed and the focus has
been returned by the web portal back to the Mobile
Plans app,
OR
The user has cancelled the flow and returned to the
Mobile Plans app.
The web portal must not display any pop-up windows, open Required
any additional windows, or redirect the user to any other
websites or apps, except as required to complete the
activation flow.
The web portal must handle all legitimate errors and Required
exceptions, such as rejection of payment method, backend
failure, etc. After the error or exception is handled, the web
portal must remain responsive for users to exit and return to
the Mobile Plans app.
If users run into an error that can be fixed with user actions, Recommended
it is recommended to display mobile operator customer
support information with the error message.
Usability
P O L IC Y REQ UIRED O R REC O M M EN DED
The default frame size for the web portal is 800x600. Mobile Required
operators should adopt responsive web design so that
content on their web portal can be auto-adjusted to fit into
the web control frame when users resize the Mobile Plans
app for larger and smaller screens.
Load times and data consumption for loading the web Required
portal experience should be optimized.
Layout of pages within the web portal should be clean and Required
easy to navigate. Users can navigate backward and forward
through pages in the web portal with UI elements within the
portal experience. For more information, see Web portal flow
and reference design.
The web portal must not be cluttered with too many images, Required
banners, lengthy text, external links, etc.
Mobile operators can choose the color scheme and fonts Recommended
that best represent their brand. Care should be taken to
ensure all visual elements work well together and reinforce
the brand.
Localization
P O L IC Y REQ UIRED O R REC O M M EN DED
Accessibility
P O L IC Y REQ UIRED O R REC O M M EN DED
Overview
Once a user finishes the activation flow in the mobile operator web portal, the portal must provide a signal to let
the Mobile Plans app know that the flow has completed. This is done by issuing a notification to the app that
includes the result of the user interaction with the web portal.
Transactions that the web portal supports include, but are not limited to, the following:
Issuing a new eSIM profile (using an activation code).
Associating the device with a new or existing subscription.
Purchasing a new data plan (either postpaid or prepaid).
Purchasing additional data for to an prepaid plan.
Canceling a subscription.
NOTE
The callback notification must be returned from the host defined in the mobile operator's Service configuration.
The eSIM profile download will begin upon receipt of the callback notificaiton. Control is returned to the web
portal immediately after the call. UI will be displayed to show the profile download progress as popup element
rendered on top of the web portal. The web portal can continue to be navigated during this process.
The following Javascript function shows an example of the API to inform the application that a profile download
should begin:
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID");
See purchase metadata properties for details about the puchaseMetadata object.
Listening for network registration changes
To listen for network registration changes, the MobilePlansInlineProfileDownload.registrationChangedScript
must be set to a string that is the name of a Javascript function that takes a string for the registrationArgs .
The registration args are a string that represents a JSON object.
ProfileRegistrationCompleteArgs
MobilePlansNetworkRegistrationState
The following Javascript example shows how to implement a listener for network registration changed events.
function onRegistrationChanged(registrationArgs) {
var registrationObj = JSON.parse(registrationArgs);
if(registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.home ||
registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.roaming ||
registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.partner)
{
Log('Registration Successful!');
}
}
MobilePlansActivationError
The following Javascript example shows how to implement a listener for the profile activation event.
function onActivationComplete(activationArgs) {
var activationObj = JSON.parse(activationArgs);
if(activationObj.activationResult == MobilePlansActivationError.success)
Log('Activation Success');
}
Control is returned to the mobile operator Portal immediately after the call. UI will be displayed to inform the
user that a profile will be installed later. After the downloadDelay minutes has occurred, a notification will be
shown to the user, inviting them to begin the process of downloading the profile.
The following Javascript function shows an example of the API to inform the application that a profile download
with delay should begin
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID", 15);
See purchase metadata properties for details about the puchaseMetadata object.
See listening for network registration changes section above.
See listening for profile activation section above.
MobilePlansInlineOperations.notifyOperationCancel(MobilePlansOperationContext)
PA RA M ET ER N A M E TYPE DESC RIP T IO N
This operation can be canceled before the user sees a toast notification informing them that download is ready
to begin.
The following Javascript function shows an example of the API to cancel an asynchronous action.
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
var op = MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData ,
"1$smdp.address$matchingID", 15);
MobilePlansInlineOperations.notifyOperationCancel(op);
Asynchronous connectivity
The following diagram shows the high level flow for how the Mobile Plans app supports delayed connectivity.
This callback method should be used when the eSIM profile is already available for release by the SM-DP+
server, however the device needs to wait some time before attempting to register on the cellular network.
After the user successfully completes the activation flow, the web portal informs the Mobile Plans app that it
should trigger the delayed connectivity flow using the MobilePlans.notifyPurchaseWithProfileDownload API.
MobilePlans.notifyPurchaseWithProfileDownload
PA RA M ET ER N A M E TYPE DESC RIP T IO N
The following Javascript function shows an example of the API to inform the application that the user purchase
requires a delayed provisioning of connectivity.
function finishPurchaseWithDownload() {
var metadata = MobilePlans.createPurchaseMetaData();
metadata.userAccount = MobilePlansUserAccount.new;
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
metadata.moDirectStatus = MobilePlansMoDirectStatus.complete;
metadata.line = MobilePlansLineType.new;
metadata.planName = "2GB Monthly";
MobilePlans.notifyPurchaseWithProfileDownload(metadata, "1$smdp.address$matchingID", 15);
}
See purchase metadata properties for details about the puchaseMetadata object.
Adding balance
When a user completes a purchase in the web portal by adding more balance to an existing account, the web
portal should invoke the MobilePlansInlineOperations.notifyBalanceAddition API return control back to the
Mobile Plans app. This could be used for physical SIM or eSIM profile which are already installed in the device.
The following diagram shows the high level flow for how the Mobile Plans app supports adding balance.
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData)
PA RA M ET ER N A M E TYPE DESC RIP T IO N
When the mobile operator would like to add balance to a given account, the web portal should call the
MobilePlansInlineOperations.notifyBalanceAddition API.
The following Javascript function shows an example of the API to inform the application that a balance addition
has been made.
function NotifyMobilePlans() {
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData);
}
See purchase metadata properties for details about the puchaseMetadata object.
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, iccid)
PA RA M ET ER N A M E TYPE DESC RIP T IO N
Balance addition can also be made to a non active profile if the ICCID of the profile is known. Using the
MobilePlansInlineOperations.notifyBalanceAddition with an ICCID will inform the app of the balance addition as
well as switch the active profile to the profile corresponding to the provided ICCID.
The following Javascript function shows an example of the API to inform the application that a balance addition
has been made.
function NotifyMobilePlans() {
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, "8900000000000000001");
}
See purchase metadata properties for details about the puchaseMetadata object.
MobilePlans.notifyCancelledPurchase
PA RA M ET ER N A M E TYPE DESC RIP T IO N
The following Javascript function shows an example of the API to inform the application that the user has
canceled a purchase.
function finishPurchaseWithCancellation() {
var metadata = MobilePlans.createPurchaseMetaData();
metadata.userAccount = MobilePlansUserAccount.new;
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
metadata.moDirectStatus = MobilePlansMoDirectStatus.cancelled;
metadata.line = MobilePlansLineType.bailed;
metadata.planName = "";
MobilePlans.notifyCancelledPurchase(metadata);
}
See purchase metadata properties for details about the puchaseMetadata object.
Overview
The Mobile Plans app has a built-in retry solution that attempts to repair situations where the eSIM profile
download does not complete successfully. However, in some scenarios, intervention from the mobile operator is
necessary to ensure that the eSIM is installed on the device. Mobile operators can support eSIM error handling
in their web portal to delight their consumers.
GET https://moportal.com/?
market=US&location=US&transactionId=HADRdRhKI0S5bN4n.1&eid=89033023422130000000000199272786&imei=00110200022
4082 HTTP/1.1
X-MP-LPAError-Codes: ServerFailure,ServerNotReachable
X-MP-LPAError-TimeStamps: 5/18/2018 11:17:23 PM,5/18/2018 11:27:33 PM
X-MP-LPAError-ICCIDs: 8988247000101997790
The Mobile Plans app adds three headers, described in the following table.
Mobile operators might choose not to support handling errors passed by the Mobile Plans app, but we
recommend doing so because it enhances the user experience.
The following image shows an example of the error message that is displayed to the user:
Mobile Operator account management in Windows
10
4/13/2022 • 7 minutes to read • Edit Online
This topic describes the mobile operator account management experience provided by Windows, which can be
extended with Mobile Plans.
To provide the right information in the network flyout, MOs provide Type and Balance (dataRemainingMB and
timeRemaining) information as defined in the GetBalance API section.
The following table provides a reference between the GetBalance response type and what is displayed in the
network flyout.
GET B A L A N C E RESP O N SE T Y P E N ET W O RK F LY O UT SH O W S. . .
GetBalance API
IMPORTANT
Please request a Windows COSA update to enable Get Balance in Windows.
The GetBalance API queries current subscription status, controls whether the Mobile Plans experience is
available on the device, and shows remaining data and time in the network flyout for prepaid subscriptions. The
following diagram shows the high-level flow for the GetBalance API.
Resource model
Communication between the Mobile Plans service and the Mobile Operator API involves manipulating the
resources in the following diagram. Explanations for each resource are in the tables following the diagram.
SIM resource
NOTE
The SIM resource does not currently support “create,” “read,” “update,” or “delete” operations.
Balance resource
Headers
The following headers may be included in every request from the Mobile Plans service to the mobile provider’s
endpoint.
Error codes
The table below defines the error codes that should be used in the HTTP response.
HTTP 200 (OK) The operation completed successfully. This code should also
be used to indicate if the user has 0 balance in the specified
location, which should be done using dataRemainingInMB=0
and timeRemaining=”PT0S” with HTTP 200.
ERRO R C O DE DESC RIP T IO N
HTTP 201 (Created) Indicates that the operation completed successfully and the
resource was created successfully.
HTTP 400 (Bad Request) Used for an invalid query parameter, invalid header, or
invalid payload. In the response body, the parameter that is
incorrect should be indicated. For example, if an invalid
fieldsTemplate is specified, this error code must be returned
with details in the response body.
HTTP 401 (Unauthorized) Authentication credentials were incorrect or invalid. This can
occur when the basic auth credentials passed are incorrect.
HTTP 403 (Forbidden) The client certificate is untrusted or invalid. If the client
certificate included as a part of MTLS is invalid, HTTP 403
should be returned.
HTTP 404 (Not Found) The MO service should return this error when the resource
doesn’t exist. This can occur when an incorrect ICCID is sent.
This should not be used to indicate that the user doesn’t
have a balance in the specified location, which is indicated
with HTTP 200 (OK).
HTTP 429 (Too many requests) Used by the MO service to indicate that the Mobile Plans
service is sending too many requests within the specified
amount of time. In the response, the MO service must use
the Retry-After header to indicate the time after which the
Mobile Plans service should retry for the resource. In the
response body, optional details can be provided.
HTTP 500 (Internal Error) Something unexpected happened on the MO service. The
MO service should include the cause of error whenever
possible so that it can be used for further debugging as
needed.
Query parameters:
The following series of examples show the call flow for the GetBalance API.
Example 1: Returning the first balance that is available for the user in US
HTTP response:
HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: “12345”
{
“balances”: [
{
“id”: “23445”,
“type”: “MODIRECTPAYG”,
“dataRemaininginMB”: 123.0,
“timeRemaining”: “P23DT23H”
}
]
}
Example 2: The expected response for a SIM that is in the COSA ICCID range but should not be supported by Mobile Plans
HTTP request:
HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: “12345”
{
“balances”: [
{
“id”: “23445”,
“type”: “NOTSUPPORTED”,
“dataRemaininginMB”: 0.0,
“timeRemaining”: “PT0S”
}
]
}
Authentication
Communication between the Mobile Plans service and the Mobile Operator API must be authenticated using the
Mutual Transport Layer Security (MTLS). Microsoft provides a certificate for you to use to validate the identity of
the requester to moBaseUrl .
Microsoft provides the certificate during the onboarding process.
How to enable Get Balance in Windows COSA
It is required to configure the following settings in the Windows COSA database to enable the Get Balance
support on Windows devices.
The following COSA settings are required:
SupportDataMarketplace (must be set to “Yes”)
DataMarketplaceRoamingUIEnabled
SIM ICCID range (ICCID Range – Start and ICCID Range – End)
For more info about all supported fields, see the Desktop COSA-only settings on Desktop COSA/APN database
settings.
Download the COSA/APN update spreadsheet.
Mobile Plans walled garden
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Plans Walled Garden is key to supporting customers when they run out of data. It enables them to
reach the MO Direct portal even when there is no alternative internet connection such as Wi-Fi. This will enable
consumers to purchase additional data plans and manage their subscriptions.
NOTE
The Mobile Plans architecture does not support IP ranges for Walled Garden endpoints. Host names must be used for
allowlisting.
The MO Direct web portal and GetBalance API endpoint must also be part of this Walled Garden.
URL HT T P/HT T PS
service.datamart.windows.com https
dogfood.datamart.windows.com https
windows.policies.live.net https
ctldl.windowsupdate.com http
cdp1.public-trust.com http
ocsp.omniroot.com http
vassg142.ocsp.omniroot.com http
vassg142.crl.omniroot.com http
mscrl.microsoft.com http
crl.microsoft.com http
www.msftconnecttest.com http
crl3.digicert.com http
Ocsp.digicert.com http
Overview
This topic describes toast notifications in Mobile Plans that can be customized by the mobile operator with text
and images to communicate with end users. Mobile Plans notifications are based on the toast notifications
framework in Windows 10.
NOTE
Please reach out your Microsoft contact before planning to use this feature.
The Mobile Plans app supports the showing of 2 different types of toast notifications: SMS-triggered and app-
triggered.
SMS-triggered notifications
Mobile operators can trigger a notification to be shown on a user's device by sending an SMS to the device. The
body of the SMS includes a string identifier which will route the message to the Mobile Plans app, and trigger
showing of the notification. Clicking on the <accept> button will launch the Mobile Plans app and show the
mobile operator's Gateway page.
Because the mobile operator triggers the notification via SMS, the device must have the active profile and be
registered on the cellular network with ability to receive the SMS. The device must also have data access to the
Mobile Plans service for requesting the notification content.
SMS -triggered notification content
The notification content can be customized by the mobile operator using a template with predefined elements.
The highlighted elements below are definable by the mobile operator.
Notification type Several pre-defined types of SMS- Low Balance, Zero Balance, New Offer,
notifications are supported. Each type Trial Offer, Trial Ending, Trial Ended
behaves the same. Only the strings
shown for the <accept> and
<decline> buttons change
depending on the type.
Body Short message highlighting the "There's less than 5MB left for your
offering value to the end user current data plan. Take action now to
make sure you stay connected."
GET https://{notificationUri}sims/{simmri}/notifications
{notificationUri} is the NotificationUri value onboarded as part of the mobile operator's service configuration.
The endpoint has three query parameters:
limit, which is required and specifies the number of notifications to return.
imei, which is optional and specifies the client’s IMEI.
notificationType, which is required and specifies the type of notifications to return. The notificationType
parameter is always one of the enumerated strings accepted by the Mobile Plans’ GET Notifications Request.
The response is a JSON object with a single property named notifications that contains a list of notifications. The
number of notifications in this list is at most limit from the request. Each notification in this list is an object with
a single property, notificationId, which must identify an existing notification in the mobile operator’s service
configuration.
The following is an example interaction using this endpoint:
GET https://moendpoint.com/v1/sims/iccid:8988247000100003319/notifications?
notificationType=lowBalance&limit=1&imei=1234
X-MS-DM-TransactionId: "MSFT-12345678-1234-1234-1234-123456789abc"
HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: "MSFT-12345678-1234-1234-1234-123456789abc"
{
"notifications": [
{
"notificationId": 1,
"notificationType": "lowBalance"
}
]
}
App-triggered notifications
Mobile operators in some markets also have the ability to show a promotional notification on eSIM-enabled
Windows 10 PCs that do not have an eSIM profile installed. The promotional notification is triggered by the app
shortly after the user completes setup of the device in the out of box experience. Clicking on the <accept>
button will launch the Mobile Plans app and show the mobile operator's Gateway page.
App-triggered notification content
The promotional notification content can be customized by the mobile operator using a template with
predefined elements. The highlighted elements below are definable by the mobile operator.
Body Short message highlighting the "Get 30GB FREE data, so you can stay
offering value to the end user connected from anywhere."
Project overview
Mobile Plans onboarding is a project composed of four phases:
P H A SE DESC RIP T IO N
Rollout & Launch The mobile operator is enabled commercially and made
available to end users in the production environment. The
launch topic provides more details on this phase.
Project schedule
A typical project schedule is divided into the following phases, with milestones defining the exit/entrance criteria
for each phase. The actual length of the devlopment phase will depend on multiple factors including the scope
of the project.
Project plan
This sample project plan has been developed to illustrate the tasks required for each phase of work. Some tasks
are for mobile operators, while others are joint tasks to be done in coordination with Microsoft.
Mobile Plans service configuration
4/13/2022 • 2 minutes to read • Edit Online
This topic describes how to build a foundation on Windows connected devices that support Mobile Plans. It
details how to configure your eSIM profiles to ensure the best consumer experience, as well as how to provide
service configuration information that ensures that the Mobile Plans experience is properly rendered on
Windows devices.
Service configuration
The Mobile Plans service must ingest some configuration information to support a mobile operator. To start the
configuration process, please send an email to Mobile Plans Implementation Support.
Minimum configuration information
1. The brand name you would like to use for your products.
2. The branding logo. Required resolution is 300x300 pixels. Image should also be full bleed with no
transparency.
3. The list of countries where your solution is supported. Please use ISO 3166 code to create the list (comma
separated).
4. Your MO Direct portal URI (localization is not supported). This should be an https address. Port numbers are
not supported.
5. A notification URI. This is the host address from where the Javascript callbacks (callback notifications) are
going to be run. This should be an https address. Port numbers are not supported.
6. The ICCID range or ranges that you want to want to associate with Mobile Plans.
The following image shows an example for the standard gateway page in the Mobile Plans app. The “A”
annotation corresponds to the branding logo you submit, and the “B” annotation corresponds to the brand
name.
Mobile Plans Integration
4/13/2022 • 2 minutes to read • Edit Online
Overview
This topic describes what steps are needed to integrate and validate the mobile operator implementation of the
Mobile Plans solution.
Validation
This section describes testing and validation that you must do to ensure that you are ready to move into the
Integration phase.
Mobile Operator web portal
Validate that you can run 50 end-to-end user cases that you defined. For example:
Install an eSIM profile.
Activate a warm SIM.
Add balance to your subscription.
Canceling a transaction.
Walled Garden
When the user has no balance, ensure that the user can access Walled Garden sites defined in Walled Garden.
Getting Balance
1. When the user is in the Walled Garden state, the balance returned must be zero.
2. As the user consumes data, the balance returned must decrement to reflect the data remaining.
3. As the allotted time lapses after the Create Order API has been invoked, the time remaining must decrement
to reflect the time remaining.
Test with expired MTLS certificate
1. Validate MO APIs without the MTLS certificate. Expected Status: 401 Unauthorized.
2. Validate with an expired MTLS certificate. Expected Status: 401 Unauthorized.
GetBalance negative tests
1. Validate with an invalid SIM. Expected Status: 404 Not Found.
2. Validate with unknown location or bad location string/number. Expected Status: 400 (Bad Request).
3. Validate with filter limit as a negative number and exceeding the limit of an INT. Expected Status: 400 - Bad
Request. Expected Status 200 OK for filter limit (integer).
4. Validate a call to GetBalance without any location (or empty location), fieldTemplate, limit, and many more
combinations of parameters. Expected Status: 400 (Bad Request) with any bad parameter’s value. Expected
Status 200 – OK.
GetBalance API load test
Before the GetBalance API is enabled in production, both Mobile Plans services and mobile operator services
should be tested to see if they can handle the projected load. The mobile operator is expected to run a load test.
Once that has passed, Mobile Plans executes a load test. The mobile operator should provide a list of 1000
ICCIDs that are temporally used in the load test.
This test configuration is generated from projected traffic of 10,000 SIMs. The Peak RPS is calculated based on 3
times this traffic projection.
Load tests will be executed from 25 test agents.
Load tests will execute for:
1 hour with 1000 different users (#ICCIDs) with 3 RPS (Peak).
The load distribution cross APIs would be as follows:
GetBalance 96% 1 3
During test runs, the expected success rate is: 99.9% and average latency: 400ms . On achieving this success
rate, the MO API will be ready to enable in the Mobile Plans production service.
Mobile Plans launch
4/13/2022 • 5 minutes to read • Edit Online
This section describes the work needed to successfully launch Mobile Plans with your mobile operator, including
Web service API monitoring, running an end-to-end scenario, and the review escalation process.
Before launch
You (the mobile operator) and Microsoft will review that all outstanding issues are properly addressed before
moving to go live. This is important to fully migrate to a production environment.
Launch validation
On the agreed-upon launch date, Microsoft will move the mobile operator portal to production. The mobile
operator is responsible for performing end-to-end validation immediately and reporting back any potential
issues to Microsoft. This will enable providing support to address the issues accordingly.
Mobile operatosr are ultimately responsible for accepting the live, in-production service.
After Launch
API monitoring
The Mobile Plans service monitors the availability of the Web service API (mobile operator portal) by using
Xping to ping the portal twice per minute, making sure it is accessible.
The Mobile Plans service monitors the availability of the GetBalance API using the defined protocol, twice per
minute, making sure it is accessible. For this monitoring the mobile operator should provide an ICCID that will
be continually used.
Escalation process
Microsoft has established a two-way live site escalation process for mobile operators and Microsoft to work
together on any customer-facing production incidents. A live site issue is any event that is not part of the
standard operation of the either your service or Microsoft’s service, and causes (or might cause) an interruption
or a reduction in quality of the Mobile Plans experience. Key scenarios in the Mobile Plans experience are:
Ensuring that the Mobile Plans app can reach your MO Direct portal via Walled Garden or a Wi-Fi or Ethernet
connection.
Ensuring users can always consume purchased data.
The goal of this process is that both mobile operators and Microsoft agree to the following:
1. Monitor and escalate live site incidents following the process described in this topic.
2. Prior to escalation of an incident, assign the correct priority using the guidelines described in this topic.
3. Provide responses on all incidents in accordance with the maximum allowed response times associated to
the incident priority as described in this topic.
Live site performance SLAs
The following table provides detailed descriptions for live site performance SLAs, including service availability
and expected API response times for key APIs integrated with the Mobile Plans service.
IN C L UDED IN
M O B IL E P L A N S
IM PA C T IN C A SE MO API
SERVIC E N A M E DESC RIP T IO N O F IN C IDEN T M O N ITO RIN G? AVA IL A B IL IT Y L AT EN C Y
Core Network Services that Users will not be No. 99.90% N/A
Services provide the able to connect Mobile
(PGW, capability to: to the internet operators
Online Access using their are
Charging the cellular data responsible
System, internet plan. for
internet for a user monitoring
access, GRX with data their own
access, etc.) allowance Core
. Network
Access Services.
Walled
Garden
even with
no data
allowance
.
MO Direct portal A web portal Users will not be Yes 99.90% 400ms
that users can able to engage
access for the with the MO
MO Direct Direct experience
scenario. to sign up data
plans.
Incident escalation
Escalation to mobile operators
If a service interruption is detected by Microsoft, the incident is triaged and processed based on the following
severity.
EXP EC T ED
SEVERIT Y B USIN ESS IM PA C T T H RESH O L D RESO L UT IO N T IM E UP DAT E C A DEN C E
Escalation to Microsoft
If you detect a service interruption, you can escalate to the Mobile Plans Services team. Service interruptions
include, but are not limited to, core Mobile Plans scenarios being down for more than 30 minutes, or mobile
operators’ services receiving an abnormally high number of calls from Mobile Plans services.
For incidents during staging / onboarding, escalate to Mobile Plans Implementation Support. For incidents post
onboarding, escalate to Mobile Plans Operations support.
Services outage
Microsoft communication of services outage to mobile operators
Microsoft will inform mobile operators of any Microsoft network Mobile Plans service outages via email no
more than 30 minutes after we first become aware of such an outage.
Mobile operator communication of services outage to Microsoft
You must inform Microsoft of any Core Network Services outages via email no more than 30 minutes after you
first become aware of such outages. Mobile Plans Operations support
Pl an n ed m ai n t en an c e
Regularly scheduled or routine maintenance of the services operated by mobile operators or the Microsoft
Mobile Plans team that have or may have end user impact must be communicated beforehand through the
channels defined in this section.
Co m m u n i c at i o n o f pl an n ed m ai n t en an c e t o m o bi l e o per at o r s
The Microsoft Mobile Plans team will communicate planned maintenance to mobile operators no later than five
business days prior to the event. Once the maintenance is completed, a notification is sent to mobile operators.
C o m m u n i c a t i o n o f p l a n n e d m a i n t e n a n c e t o M i c r o so ft
Regularly scheduled or routine maintenance of the mobile operator’s Core Network Services must be
communicated via email to Microsoft no later than five business days prior to the event to Mobile Plans
Operations support.
R e q u e st i n g b u g fi x e s
Repor ting a bug – Each team can report a bug via email to Mobile Plans Operations support, and work with
their counterparts to get a bug logged.
Customer Support
Mobile operators are solely responsible for any customer support issues.
Mobile Plans general appendix
4/13/2022 • 4 minutes to read • Edit Online
This shows an example of transaction confirmation, which is part of the mobile operator portal.
Once the order is processed successfully and, in this case, after clicking “Continue,” the notification
should be posted to the Mobile Plans app with the purchase result, eSIM activation code, and other
information required in the API. The user will be automatically redirected to the Mobile Plans app PDP
(product details page).
If the transaction is for a physical SIM card or the active eSIM profile is in place, you should be
activating the plan in the backend.
If the transaction requires a new profile to be downloaded, move on to the next step.
7. Downloading an eSIM profile (if applicable):
IMPORTANT
Build your MO Direct portal as if you are building a shopping cart experience if you would like the user to return to the
previous state without losing any data they had entered.
MO Direct portal
development start
P H A SE A C T IVIT IES O W N ER T IM E EST IM AT E
GetBalance API
development start
MO Direct portal MO
development complete
GetBalance API MO
development complete
MO development complete MO
- code complete
(checkpoint)
End-to-end experience is MO
functional in MO Staging
Environment (checkpoint)
Update Service MO
Configuration document to
reflect Production
Environment settings (if not
provided previously)
End-to-end experience is MO
functional in MO
Production Environment
(checkpoint)
Commercial agreement MO
completed
NOTE
This page documents Mobile Plans legacy callback notifications. Please use this as reference only and do not implement
this code going forward.
When the MO Direct portal is ready for a profile download, install, and activation to occur, the portal should call
MobilePlansInlineProfile.notifyInlineProfileDownload .
MobilePlansInlineProfile.notifyInlineProfileDownload
PA RA M ET ER N A M E TYPE DESC RIP T IO N
The following Javascript function shows an example of the API to inform the application that an inline profile
download should start.
function NotifyMobilePlans() {
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineProfileDownload.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineProfileDownload.profileActivationCompleteScript = "onActivationComplete";
MobilePlansInlineProfileDownload.notifyInlineProfileDownload(purchaseMetaData ,
"1$smdp.address$matchingID");
}
See purchase metadata properties for details about the puchaseMetadata object.
MobilePlans.notifyBalanceAddition
PA RA M ET ER N A M E TYPE DESC RIP T IO N
The following Javascript function shows an example of the API to inform the application that the user has
completed a purchase using a profile already available, but not necessarily active, on the eSIM.
function finishPurchaseWithBalanceAddition() {
var metadata = MobilePlans.createPurchaseMetaData();
metadata.userAccount = MobilePlansUserAccount.new;
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.none;
metadata.moDirectStatus = MobilePlansMoDirectStatus.complete;
metadata.line = MobilePlansLineType.new;
metadata.planName = "2GB Monthly";
MobilePlans.notifyBalanceAddition(metadata, "89000000000000000000");
}
See purchase metadata properties for details about the puchaseMetadata object.
DataMart.notifyPurchaseResult(notificationPayload);
DataMart.notifyPurchaseResult(JSON.stringify(notificationPayload));
DataMart.notifyPurchaseResult(JSON.stringify(notificationPayload));
An example of the notification payload for an eSIM where the user abandoned the MO portal without a
successful transaction is as follows. To implement all cases that apply to your specific implementation, see the
table that follows the example.
let notificationPayload = new Object();
notificationPayload.ver = '1';
notificationPayload.purchaseResult = "
{\"userAccount\":\"Bailed\",\"purchaseInstrument\":\"None\",\"line\":\"None\",\"moDirectStatus\":\"None\",\"
planName\":\"\"}";
notificationPayload.success = false;
notificationPayload.transactionId = 'MSFT_ecf5a4d6-024c-46c3-8fcd-2c1f0deed572';
notificationPayload.activationCode = '';
notificationPayload.iccid = '';
DataMart.notifyPurchaseResult(JSON.stringify(notificationPayload));
The MO Portal URI from which the notification is sent must be in the secure https protocol. You can specify the
host but not necessarily the full path, which leaves some flexibility for the future.
The following table describes each field in the JSON payload of the notification:
Internet Sharing, commonly referred to as tethering, has been added in Windows 8.1 to enable users to share
their mobile broadband network connection with one or more other devices that are not mobile broadband-
capable. Traditional tethering mechanisms include Bluetooth and USB. However, Wi-Fi can provide the fast and
easy mobile broadband connection sharing mechanism, such as personal hotspots, mobile hotspots, and so on,
since it requires little configuration, enables high-speed data transmission, and relies on the familiar Wi-Fi
connection process.
Windows 8.1 and Windows 10 extend the Internet sharing capability further by enabling customers to turn on
and connect to PCs that have Internet Sharing configured, known as a tethering access point, just as if it was a
standard Wi-Fi network.
A Packet Data Protocol (PDP) context offers a packet data connection over which a device and the mobile
network can exchange IP packets. As per 3GPP standards, a device can have more than one PDP context
activated at a time. In Windows 8.1 and Windows 10, multiple PDP contexts are supported and enables apps to
communicate over special PDP contexts to the mobile networks along with the internet PDP context that was
supported in Windows 8. You can use this feature to create differentiated experiences and innovative services on
Windows. You can also partner with app developers to develop great quality VOIP and video streaming
experiences for their customers.
Here’s a figure that shows how multiple PDP context works in Windows 8.1 and Windows 10:
Use the following sections in this topic to learn more about multiple PDP contexts:
Key scenarios
Mobile broadband apps
Mobile broadband devices
Key scenarios
You can use multiple PDP contexts to enable premium services.
Differentiated Billing – You can vary the data or billing restrictions by using multiple PDP contexts. For
example, Contoso is a mobile operator that developed a data backup app for their customers. As a mobile
operator, Contoso could create multiple PDP contexts and let premium subscribers use the app for free.
All other subscribers are charged separately to use it.
Rich Communication Ser vices – A global initiative created by the GSM Association to provide rich
communication services, such as an enhanced phonebook, enhanced messaging, and enriched calling.
Rich Communication Services provide interoperability across mobile operators and offers new ways to
use existing assets and capabilities to deliver high quality and innovative communication services.
Sponsored Connectivity – This allows users to a specific type of content without it going against their
monthly data usage. The content provider makes an arrangement to reimburse the mobile operator by
paying them directly, doing a revenue-sharing deal, or some other business arrangement.
Personal Hotspot – Some mobile operators charge different rates when the connection is being used as
a personal hotspot. You can use multiple PDP contexts to differentiate between the two.
Networking APIs
For sending data by using a special PDP context, the Microsoft Store app must use different logic based on
networking APIs that it uses for transferring data.
HTTP-based APIs
HTTP-based APIs, such as XMLHTTPRequest , IXHR2, Windows.Web.Syndication , and
Windows.Web.AtomPub , and APIs based on the Windows HTTP protocol, such as JQuery and
Windows.Web.Http , do not have the ability to bind to a specific interface. For these APIs, Windows handles the
routing of data to a special PDP context by using policies. Once the special PDP context is activated, the app can
specify routing rules based on destination and special PDP context. The destination can be domain name or IP
address, such as video.fabrikam.com, .contoso.com, or 123.23.34.333. After specifying the routing rules, if the
app uses any of the above HTTP APIs to transfer the data, Windows will send the data to the special PDP context
based on routing rules. Once the app has finished transferring data, it should disconnect the special PDP context
and remove the route policy.
NOTE
Background Transfer APIs and HTTP Client(C#) APIs cannot use a route policy.
Socket-based APIs
Socket-based APIs available in the Windows.Networking.Sockets namespace, such as TCP, UDP, and stream
sockets, provide a mechanism to bind to a specific interface. When an app uses the socket APIs, it should bind to
specific interface for routing data to the special PDP context. Once the special PDP context is activated, the
AcquireConnectionAsync API provides the interface information to the app. It can use this information to
bind to a specific interface and start transferring the data.
// On successful Activation of APN, Windows returns a ConnectionSession object that encapsulates the new
connection profile
function onConnectionSucceeded(result
{
// keep the connectionSession in scope
currentConnectionSession= result;
// Backend data interaction with appropriate HTTP APIs (IXHR, Open IFrame etc.)
The following code shows you how to use these APIs for a socket-based data transfer:
// Connect to Special PDP Context
var connectivity = Windows.Networking.Connectivity;
var currentRoutePolicy = null;
var currentConnectionSession = null;
// On successful activation of an APN, Windows returns a ConnectionSession object that encapsulates the new
connection profile
function onConnectionSucceeded(result) {
function onSocketConnectionSucceeded(result)
{
// Start transferring data using socket APIs
Your app must handle NetworkStatusChanged event to handle any network transitions on the special PDP
context connection.
Scenario: Premium mobile broadband app provides free data access using special APN
In this scenario, the mobile broadband app provides free data access using a special PDP context. The app either
uses a connected network, such as a Wi-Fi network, if it is free or it uses a special APN if connected to a specific
operator network. The following sample code illustrates how an app can use the multiple PDP context APIs for
transferring data on a special PDP context if no free networks are connected.
}
else
{
onFailure();
}
}
//
// request the connection to Windows
connectivity.connectivityManager.acquireConnectionAsync(apnContext).done(onConnectionSucceeded,
onConnectionFailed);
}
// on success Windows returns a ConnectionSession object that encapsulates the new connection profile
function onConnectionSucceeded(result)
{
// keep the connectionSession in scope
currentConnectionSession= result;
// create a route policy for the new connection
enforceHttpRoutePolicy(currentConnectionSession.ConnectionProfile,new
hostName("video.mydomain.com"),Windows.Networking.DomainNameType.suffix);
// cleanup on shutdown
function onShutdown()
{
{
// Remove the route policy from HttpStack
connectivity.connectivityManager.removeHttpRoutePolicy(currentRoutePolicy);
currentRoutePolicy = null;
Scenario: Mobile broadband app requires special PDP Context for subscription purchase and provisioning
In this scenario, the mobile broadband app requires a special PDP context for subscription purchase and
provisioning. This app will activate a special PDP context regardless of the connected network.
var connectivity = Windows.Networking.Connectivity;
var currentRoutePolicy = null;
var currentConnectionSession = null;
function onLoad()
{
// Register for network status change
connectivity.networkInformation.addEventListener("networkstatuschanged", OnNetworkStatusChange);
// Process the current status
handleNetworkChange();
}
function onNetworkStatusChange()
{
HandleNetworkChange();
}
// On successful connection to PDP Context, Windows returns a ConnectionSession object that incapsulate
the new connection profile
function onConnectionSucceeded(result)
{
// keep the connectionSession in scope
currentConnectionSession= result;
function handleNetworkChange()
{
// App behavior to handle network
var currentProfile = currentRoutePolicy.connectionProfile();
if (NetworkConnectivityLevel.none != currentProfile.GetNetworkConnectivityLevel())
{
// The special PDP Context is disconnected, app should handle this. It can request another connection to
special PDP Context or it can show error to the user.
}
}
Considerations for mobile broadband apps
Mobile broadband apps can get local data usage information for each PDP context and influence Windows with
policies for special PDP contexts.
Local data usage
In Windows 8, you provide an ongoing subscription-based relationship with users through your mobile
broadband app which has the ability to show current data usage. Users can view their current data usage and
understand their billing cycle or session end date to make an appropriate decision. To reduce the load on the
network as much as possible, you should check the data usage with the network periodically. Windows provides
a local Data Usage API that you can use to combine with data usage to show the current data usage to user.
A special PDP context provides you the ability to differentiate data access charges to certain apps or services.
Each different PDP context is treated as a different profile for local data usage counters. The mobile broadband
app can query the local data usage for each PDP context for a particular duration, similar to how the internet
PDP context worked in Windows 8. You can use this information to show appropriate data usage experience to
the user.
The following sample code demonstrates how you can use the networking APIs to read local data usage for all
PDP contexts:
if (networkAccIds.Count == 0)
{
rootPage.NotifyUser("No network account ID found", NotifyType.ErrorMessage);
return;
}
// For the sake of simplicity, assume we want to use the first account.
// Refer to the MobileBroadbandAccount API's how to select a specific account ID.
string networkAccountId = networkAccIds[0];
Policies
Some operators have indicated that special PDP contexts have limited bandwidth. Apps that activate the special
PDP context but do not have access to use the special PDP context can create a denial of service attack. You
should restrict the usage of special APNs to specific apps with a business relationship. You are able to provide
Windows a list of UWP apps with special APN names. Windows will use that information to limit the access to
special APNs. If you do not provide a list, Windows assumes that the special PDP context is open for all apps.
NOTE
This is just to avoid extra traffic on special PDP contexts. You cannot rely on this as a security mechanism for restricting
apps to special PDP contexts. If you would like to restrict access to special PDP contexts, you must implement some
authentication or security mechanism on your network. For example, you could use a filter that allows only certain IP
addresses for a specific PDP context.
Some mobile networks do not support multiple PDP contexts. You can provision whether your network
supports multiple PDP context or not. If your network doesn’t support multiple PDP contexts, Windows should
not allow apps to create on-demand connections on special APNs. By default, Windows assumes you support
multiple PDP contexts.
The following sample XML file demonstrates how to use Windows provisioning metadata to provide an allowed
app list for special PDP contexts:
<?xml version="1.0" encoding="utf-8"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<!-- Adjust the Carrier ID to fit your own ID. Refer to the documentation about Carrier ID's. -->
<CarrierId>{11111111-1111-1111-1111-111111111111}</CarrierId>
<!-- Adjust the Susbscriber ID. Refer to the documentation about Subscriber ID's. -->
<SubscriberId>1234567890</SubscriberId>
</Global>
<Extensions>
<Extensions_v2 xmlns="http://www.microsoft.com/networking/CarrierControl/v2">
<AdditionalPDPContexts>
<MultiplePDPContextPolicies MultiplePDPContextSupport="true">
<PDPContextPolicy>
<!-- Adjust the profile name -->
<Name>Contoso1</Name>
<Context>
<!-- Adjust the access string to your APN. -->
<AccessString>Contoso.Contoso1</AccessString>
<!-- Adjust the UserLogonCred to fit your UserLogonCred. Refer to the documentation about
UserLogonCred's. -->
<UserLogonCred>
<UserName>user1</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
<AppIDList>
<!-- Adjust the AppId to your AppId -->
<AppID>Contoso.Sample1.CS_dsarewaj</AppID>
<AppID>Contoso.Sample2.CPP_dsarewaj</AppID>
</AppIDList>
</PDPContextPolicy>
<PDPContextPolicy>
<!-- Adjust the profile name -->
<Name>Contoso2</Name>
<Context>
<!-- Adjust the access string to your APN. -->
<AccessString>Contoso.Contoso2</AccessString>
<!-- Adjust the UserLogonCred to fit your UserLogonCred. Refer to the documentation about
UserLogonCred. -->
<UserLogonCred>
<UserName>user2</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
<AppIDList>
<!-- Adjust the AppId to your AppId -->
<AppID>Contoso.Sample3.CS_dsarewaj</AppID>
<AppID>Contoso.Sample4.CPP_dsarewaj</AppID>
</AppIDList>
</PDPContextPolicy>
</MultiplePDPContextPolicies>
</AdditionalPDPContexts>
</Extensions_v2>
</Extensions>
</CarrierProvisioning>
InstantGo
InstantGo provides an instant on, instant off user experience that users have come to expect on their phone. And
just like on the phone, InstantGo enables the system to stay fresh, up-to-date, and reachable whenever a suitable
network is available. InstantGo on low-power PCs platforms must meet specific Windows Certification
requirements.
The following scenarios are supported in InstantGo:
Updating live tiles with fresh content
Receiving email
Downloading files from, or uploading them to, a website
Sharing content, such as photos on a website
Receiving instant messages
Receiving VoIP calls
Communicating in real-time
Playing background audio and music
For more info on InstantGo, see Introduction to InstantGo.
Your mobile broadband app can use a special PDP context for enabling some of these InstantGo scenarios. You
need to use following logic to reconnect to the special PDP context if it is disconnected because it is out of
coverage. When the device enters the Connected Standby power state, Windows will disconnect all the
connections to special PDP contexts after 10 minutes and your app has to request the connection again.
Windows 8, Windows 8.1, and Windows 10 provide a Short Message Service (SMS) text messaging platform for
mobile network operators, mobile broadband adapter IHVs, OEMs, and their partnered software vendor’s app
with SMS access into a UWP app.
Note A mobile broadband app requires SMS support to show notifications to the end user when text
messages are received. SMS might also be required to conform to regulatory requirements or best practices in
certain markets.
The Mobile Broadband SMS platform provides the following functionality:
Send and read SMS data in text-mode or PDU-mode (binary)
Filter for data cap overage, roaming, and other administrative SMS operator notifications
New SMS received background event
Read and delete messages from the mobile broadband device message store
Get properties of the mobile broadband device
SMS API access prompt
The sections in this topic include:
Mobile broadband SMS supported devices
Access to mobile broadband SMS
SMS notifications filtering
Developing your SMS app
Basic requirements
The computer must be running Windows 8, Windows 8.1, or Windows 10, a mobile broadband device,
and active service from a mobile network operator.
The device should be hardware certified for Windows 8, Windows 8.1, or Windows 10 with the SMS
send/receive capabilities set.
Both internal and external devices are supported.
Global System for Mobile Communications (GSM)- and Code division multiple access (CDMA)-based
devices are both supported.
Additional guidance for a better user experience
An SMS message can be sent or received by an app when the device is in a network coverage area for the
supported operator. Devices must be registered to the network service provider, but do not need to be
connected to data services to send or receive messages.
Sending or receiving SMS data while on a roaming network is subject to additional fees based on the
mobile network operator (MNO) policy.
Devices cannot send or receive SMS data if the device is PIN locked.
SMS client apps should use SMS device storage as a message queue. Total SMS storage on devices varies, but
device storage is commonly limited to 30 messages.
The Mobile Broadband SMS platform is designed to maintain the ability to receive new incoming SMS messages
by freeing up SMS device storage space while minimizing deletion of user data.
Devices can’t receive new SMS messages if SMS storage becomes full. Windows automatically deletes old SMS
messages from device storage to ensure the ability to receive new incoming SMS data, such as important
mobile network operator notifications.
We recommend the following:
SMS client apps should use local app storage to maintain message history instead of relying on device
SMS storage.
SMS client apps should not delete messages on read. SMS client apps should let Windows automatically
delete old messages when device storage gets full.
Related topics
Developing SMS apps
Enumerate SMS devices
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Broadband SMS platform provides the ability to get the first SMS-capable mobile broadband device,
or to get a list of all SMS-capable mobile broadband devices. The following sample code shows instantiating an
SMS object with the default SMS device and with a specific device.
Note In apps that use C# or C++ in Windows 8, Windows 8.1, or Windows 10, the first use of the SmsDevice
object to call GetDefaultAsync or FromIdAsync should be on the STA thread. Calls from an MTA thread can
result in undefined behavior.
JavaScript code example to use the default SMS device
try
{
var smsDeviceOperation = Windows.Devices.Sms.SmsDevice.getDefaultAsync();
smsDeviceOperation.done(smsDeviceReceived, errorCallback);
}
catch (err)
{
// handle error
}
Windows.Devices.Enumeration.DeviceInformation.findAllAsync(Windows.Devices.Sms.SmsDevice.getDeviceSelector()
).then(function (smsdevices)
{
if (smsdevices.length > 0)
{
// for simplicity we choose the first device
var smsDeviceId = smsdevices[0].Id;
var smsDeviceOperation = Windows.Devices.Sms.SmsDevice.fromIdAsync(smsNotificationDetails.deviceId);
smsDeviceOperation.done(function (smsDeviceResult)
{
smsDevice = smsDeviceResult;
}, errorCallback);
}
}
// detect if SMS access is denied due to user not granting app consent to use SMS or if metadata is
missing or invalid.
function errorCallback(error)
{
WinJS.log(error.name + " : " + error.description, "sample", "error");
// If the error was caused due to access being denied to this app
// then the HResult is set to E_ACCESSDENIED (0x80007005)
function hex(nmb)
{
if (nmb >= 0)
{
return nmb.toString(16);
}
else
{
return (nmb + 0x100000000).toString(16);
}
}
Related topics
Developing SMS apps
Get SMS device information
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Broadband SMS platform provides information about the mobile broadband device, including
account phone number, status, and cellular class.
JavaScript code example for getting an SMS device mobile number
Related topics
Developing SMS apps
Read received SMS by using the text-mode
interface
4/13/2022 • 2 minutes to read • Edit Online
You can choose between using the text-mode read interface, which is suitable for simple plain text SMS
messages, or the PDU-mode mode read interface, which is suitable for advanced control of decoding SMS
messages.
Received messages are stored in encoded format on mobile broadband devices. The Mobile Broadband SMS
platform supports decoding received messages to plain text. The character sets that are supported for decoding
received messages are the same as the character sets supported for encoding messages sent.
The following table lists the character encodings supported by the text-mode API:
C H A RA C T ER L IM IT F O R
C H A RA C T ER L IM IT F O R M ULT I- PA RT SM S
N ET W O RK T Y P E C H A RA C T ER SET S SIN GL E SM S SEGM EN T SEGM EN T S
JavaScript code example for reading received SMS messages using the text-mode interface
try
{
if (smsDevice!= null)
{
var messageStore = smsDevice.messageStore;
var messageID = id('whichMessage').value;
getSmsMessageOperation.operation.completed = function ()
{
result = getSmsMessageOperation.operation.getResults();
var readableMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(result);
id('fromWho').innerHTML = readableMessage.from;
id('fromMessageBody').innerHTML = readableMessage.body;
console.log("Successfully retrieved message " + messageID + " from message store.");
}
getSmsMessageOperation.operation.start();
}
else
{
console.log("No SMS Device Found");
}
}
catch (err)
{
console.log("SMS did not set up: " + err);
}
Note SMS client apps can use the decoded segmentation information that is provided by Windows to
concatenate multiple segments of a long message and reconstruct the full message. For more info about
segmented SMS messages, see Windows automatically segments long messages.
Related topics
Developing SMS apps
Run new SMS received background events
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Broadband SMS platform provides separate system events for new SMS data that is received,
depending on whether it’s an administrative SMS notification from a mobile network operator or a general SMS
message. The background system event for a new administrative SMS notification that is received from a mobile
network operator is only accessible by a mobile broadband app.
Apps must have already received user consent to use SMS to read new received SMS messages in a background
tasks. Apps cannot read the contents of a new received SMS message from a background task if they are
accessing SMS for the first time, because the app cannot trigger the system SMS device consent prompt from a
background task.
The following code examples demonstrate a background task that is designed to run when a new SMS message
is received.
C# background task code
namespace SmsBackgroundSample
{
public sealed class SmsBackgroundTask : IBackgroundTask
{
// The Run method is the entry point of a background task.
DisplayToastAsync(taskInstance, manualEventWaiter);
// Wait until the async operation is done. We need to do this else the background process will exit.
manualEventWaiter.WaitOne(5000);
stringElements.Item(0).AppendChild(toastXml.CreateTextNode(smsTextMessage.From));
stringElements.Item(1).AppendChild(toastXml.CreateTextNode(smsTextMessage.Body));
manualEventWaiter.Set();
}
builderAway.setTrigger(triggerAway);
builderAway.taskEntryPoint = "HelloWorldBackground.BackgroundTask1";
builderAway.name = "Sms";
Related topics
Developing SMS apps
Send SMS by using custom character sets
4/13/2022 • 2 minutes to read • Edit Online
If you need access to raw message protocol data units (PDU) to achieve scenarios that are not supported by the
text-mode interface, Windows 8, Windows 8.1, and Windows 10 enable PDU-mode sending and reading
received SMS messages.
You might need to use the PDU-mode SMS interface in the following cases:
To send or read received SMS by using a National Language Single Shift Table or National Language
Locking Shift Table as defined in 3GPP TS 23.038.
To send multi-part SMS using different character sets for each segment.
JavaScript code example to send SMS messages by using the PDU-mode interface
function smsDevicePDUSend()
{
if (smsDevice !== null)
{
// Defines a binary message
var smsMessage = new Windows.Devices.Sms.SmsBinaryMessage();
var messsagePdu = “0011000B914152828377F90000AA0CC8F71D14969741F977FD07”;
var messagePduByteArray = hexToByteArray(messsagePdu);
smsMessage.setData(messagePduByteArray);
sendSmsMessageOperation.done(function (reply) {
WinJS.log("Sent message in PDU format", "sample", "status");
}, errorCallback);
}
// Used to convert hex PDU to byte array for sending SMS using PDU //mode
function hexToByteArray(hexString)
{
var result = [];
var hexByte = "";
var decByte = 0;
for (var i = 0; i < hexString.length; i = i + 2) {
hexByte = hexString.substring(i, i + 2);
decByte = parseInt(hexByte, 16);
result.push(decByte);
}
return result;
}
JavaScript code example to read received SMS messages by using the PDU-mode interface
function smsDeviceRead()
{
try
{
if (smsDevice !== null)
{
var messageStore = smsDevice.messageStore;
var messageID = “1” // select a Message Id to read
function smsMessageReadSuccess(smsMessage)
{
try
{
if (smsMessage instanceof SmsBinaryMessage) {
var format = smsMessage.format;
var pduData = smsMessage.getData(); // byte array
}
catch (err)
{
WinJS.log("SMS did not set up: " + err, "sample", "error");
}
}
Related topics
Developing SMS apps
Calculate characters and segments of a draft SMS
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Broadband SMS platform provides a function to estimate the number of characters remaining and
number of segments used (in a multi-part messages) during the composition of an SMS message.
Note The number of characters in each segment is not constant, and it varies based on the text string in the
message body and the network type. On GSM networks, a single SMS message supports up to 160 7-bit
characters or 70 16-bit characters. A message that spans multiple segments supports 142 7-bit characters in
each segment due to additional header information.
Providing an accurate estimate on the number of segments that are used while composing an SMS message
promotes user confidence, because users are typically charged per SMS message that is sent.
JavaScript code example
Related topics
Send SMS by using the text-mode interface
Specify mobile telephone numbers
4/13/2022 • 2 minutes to read • Edit Online
Telephone numbers must be specified in ITU E.164 format. SMS clients are encouraged to store telephone
numbers in ITU E.164 international format and use a library to convert ITU E.164-format telephone numbers
into a regional, common written format.
The following table is an example:
Related topics
Send SMS by using the text-mode interface
Windows automatically segments long messages
4/13/2022 • 2 minutes to read • Edit Online
The Mobile Broadband SMS platform automatically segments long messages that are sent on GSM networks
into separate segments that fit in the supported maximum character limit based on message contents.
Segmentation information (that is, part 1 of 2) is encoded in SMS User Data Header (UDH), to enable the
receiving SMS client to combine segments into a single message. All segments of a multi-part SMS are encoded
by using the same character set.
Mobile network operators charge users per message segment. SMS platform automatically creates a maximum
of 10 segments and truncates text above the limit.
Related topics
Send SMS by using the text-mode interface
Windows automatically selects optimal character
encoding
4/13/2022 • 2 minutes to read • Edit Online
Windows 8, Windows 8.1, and Windows 10 choose the optimal character encoding to use when it sends a SMS
message, based on the most efficient encoding that is supported by the message contents. SMS is encoded in a
7-bit character set, unless it contains at least one invalid character, in which case the whole message is encoded
in Unicode.
Optionally, you can override the optimal encoding functionality and specify which character set to use.
Windows 8, Windows 8.1, and Windows 10 support common character sets for mobile broadband network
adapters that are compatible with GSM (3GPP) and CDMA (3GPP2) networks.
The following table lists the character encodings supported by the text-mode API:
C H A RA C T ER L IM IT F O R
C H A RA C T ER L IM IT F O R M ULT I- PA RT SM S
N ET W O RK T Y P E C H A RA C T ER SET S SIN GL E SM S SEGM EN T SEGM EN T S
Related topics
Read received SMS by using the text-mode interface
Set SMS declarations
4/13/2022 • 2 minutes to read • Edit Online
<Capabilities>
<DeviceCapability Name="sms" />
</Capabilities>
<PrivilegedApplications>
<Package>
<Identity Name="Microsoft.SDKSamples.SMSSendReceive.JS" Version="1.0.0.0" Publisher="CN=Contoso
Corporation, O=Contoso Corporation, L=Redmond, S=Washington, C=US" />
</Package>
Related topics
Developing SMS apps
Introduction to enabling mobile broadband (MB)
experiences using portable hotspot devices
4/13/2022 • 2 minutes to read • Edit Online
The topics in this section provide information about portable Wi-Fi hotspots for Windows 8, Windows 8.1, and
Windows 10. It provides guidelines for device manufacturers to offer experiences on a Wi-Fi hotspot that is
backed by mobile broadband (including a mobile phone), that are similar to experiences that Windows offers on
a native mobile broadband connection.
Windows 8, Windows 8.1, and Windows 10 modify operating system behavior for metered networks and
provides cost information to applications so they can do the same. However, without input from the carrier, the
default assumptions are that mobile broadband is metered and that Wi-Fi and Ethernet are unrestricted.
Because Windows cannot detect the second-hop media type, the operating system cannot provide defaults that
account for mobile broadband-backed Wi-Fi networks.
By leveraging the features that are described in this topic, a device manufacturer can provide the appropriate
feedback to Windows about the second hop and thereby enable these features to function correctly when the
mobile broadband interface is not directly attached to the computer.
In collaboration with the operator, a manufacturer can optionally offer a UWP mobile broadband app that allows
the user to reference their account, including data usage.
The following topics are available in this section:
Communication channels
Related topics
Overview of mobile broadband
Personal hotspot communication channels
4/13/2022 • 2 minutes to read • Edit Online
Because the mobile broadband interface is not directly attached to the computer, information from the operator
must be exchanged by using the personal hotspot device, as shown in the following figure:
You have two opportunities to influence the data provided by the device: in firmware at the time of setup, and by
using proprietary back channels (usually web services) that are used by the device during its operational
lifetime. These protocols are outside the scope of Microsoft’s design.
All required functionality can be implemented by the device manufacturer by using data that is provided by the
carrier as part of the firmware or initial configuration. Optional functionality can require the availability of real-
time updates.
The following topics are available in this section:
Network cost information element
PnP-X for mobile broadband apps
Related topics
Enabling mobile broadband experiences using portable hotspot devices
Network cost information element
4/13/2022 • 3 minutes to read • Edit Online
To communicate the cost of the Wi-Fi network to clients, Microsoft has defined a vendor extension to the 802.11
protocol. This extension is the Network Cost IE.
Note The 802.11 protocol allows vendor-defined information elements (IEs), and requires clients that do not
understand a particular IE to ignore it and continue processing the remaining IEs. This minimizes the
compatibility risk of adding a new IE to products that interact with existing clients of other operating system
types.
The following table shows the Network Cost IE format:
The following table shows the possible Cost Level bits (exactly one is required):
The following tables shows the possible Cost flag bits. Those values MAY be or'ed
0x01 Over Data Limit Usage has exceeded the data limit
of the metered network; different
network costs or conditions might
apply.
0x08 Approaching Data Limit Usage is near the data limit of the
metered network; different
network costs or conditions might
apply once the limit is reached.
The following table shows some sample cost attribute values (last four bytes of IE):
Portable Hotspot Default 0x02, 0x00, 0x00, 0x00 Metered network; limit unknown
or not yet reached; matches
Windows default for mobile
broadband connections.
Over Limit / Throttled 0x01, 0x00, 0x01, 0x00 User has exceeded data limit;
speed is reduced, but no further
usage limitation applies.
Over Limit / Charges 0x04, 0x00, 0x01, 0x00 User has exceeded data limit;
additional usage incurs
incremental charges.
Related topics
Communication channels
[MS-NCT] Network Cost Transfer protocol documentation
PnP-X for mobile broadband apps
4/13/2022 • 2 minutes to read • Edit Online
App installation
A mobile broadband adapter offers users the opportunity to have the appropriate mobile broadband app
automatically installed when the adapter is connected. Personal hotspots cannot benefit from the same SIM-
based carrier detection. However, personal hotspots that implement the PnP-X protocol can select an app to
install. The app is automatically installed when the computer pairs with the PnP-X device.
This can be the same app that is auto-installed for mobile broadband users, or a branded app that the device
manufacturer and the operator author together. The app should include many of the same functions as a
standard mobile broadband app. See Designing the user experience of a mobile broadband app for suggestions
on standard experiences in a mobile broadband app.
Certain classes of network devices are automatically paired; for more information, see UWP device apps for
internal devices. Other device classes do not automatically install the app until the user pairs with the device by
using the computer settings.
App privileges
Although the app does not have access to the same privileged APIs as a mobile broadband app, it can talk to the
device over the network to retrieve equivalent information if the device exposes this information.
Related topics
Communication channels
Introduction to enabling mobile operator
notifications and system events
4/13/2022 • 2 minutes to read • Edit Online
This topic provides information about the Mobile Operator Notification system event. It provides guidelines for
you to develop UWP mobile broadband apps that handle incoming SMS- or USSD-based mobile operator
notifications and relevant mobile broadband system events.
Introduction
A customer’s primary experience of a mobile broadband network brand is the mobile broadband app. This app
is not expected to provide primary connection management functions, but instead provides an account
management experience and a service experience. To keep the user informed about their account status, the app
must perform some activities even when the user is not interacting with it. These activities include the following:
Responding to operator SMS or network-initiated USSD messages
Notifying the user that they are approaching their data limit
Notifying the user that their data plan has expired
Notifying the user of their roaming status
Verifying whether tethering is supported on the user’s data plan
Background brokered work items
Although UWP mobile broadband apps can run full screen, users are only expected to interact with the
application that is in the foreground. The foreground app is assumed to be the most important to the user, so
this app receives all the resources of the system. When an app is not in the foreground, it is suspended and
cannot run any code. A suspended app remains suspended until the user resumes it by bringing the app back to
the foreground. With this model of app behavior, the user experience is never affected by lags or delays caused
by the execution of unimportant background apps. In addition, reducing unnecessary background activity
optimizes battery life on a variety of form factors. The time taken to resume a suspended app is negligible and
would appear to be almost unnoticeable to most users.
Windows 10 provides Windows push notifications that can keep the app tile up-to-date even when the app is
suspended. Push notifications are optimized for system performance and longer device battery life, so it’s best
to use Windows push notifications whenever possible. If a suspended app must run its own code to do other
kinds of work, you can create background tasks.
Although UWP apps cannot run any code if they are not running in the foreground, the System Event Broker lets
you run code in response to events while an app is in the background. Apps can register work items with the
System Event Broker to respond to specific background brokered events. Windows runs the app’s work item
when background brokered events are triggered, regardless of the app’s current state (active or suspended).
In general, background events are intended as simple trigger points and are not intended to signal large
amounts of processing. As such, quotas for each app are placed on the processing time that is allowed for
background events. The background events offered by the Network Operator API, including the
MobileOperatorNotification event and HotspotAuthentication event, are treated by Windows as critical events.
Compared to general background events, background work items associated with
MobileOperatorNotification and HotspotAuthentication events run for every instance of the event
regardless of a processing time quota, although each instance of the background work item is subject to a
processing time quota. You should limit processing in the background event handler and defer larger processing
to the mobile broadband app.
In this section
Develop an app to handle the MobileOperatorNotification event
Mobile operator notification event technical details
Mobile operator notification scenarios
Develop an app to handle the
MobileOperatorNotification event
4/13/2022 • 12 minutes to read • Edit Online
This topic explains how to develop a mobile broadband app that handles the MobileOperatorNotification event.
Best practices
Step 1: Background task contract declaration
Step 2: Background task handler
Step 3: Handle the Activation event
Step 4: Handle background task completion handlers
Troubleshooting
Sample backgroundtask.js file
Best practices
For background event handling, you should use the following best practices:
Do not register for background events on which you can’t take action. Processing these events will
needlessly consume the app quota.
Do not perform large amounts of processing on receipt of a background event.
Consider deferring processing to the next time the app is launched.
Consider showing a toast notification and updating tile in response to a background event. Your mobile
broadband app can process the background event payload.
namespace MNOMessageBackground
{
public sealed class MNOBackgroundTask : IBackgroundTask
{
public void Run(Windows.ApplicationModel.Background.IBackgroundTaskInstance taskInstance)
{
NetworkOperatorNotificationEventDetails notifyData =
(NetworkOperatorNotificationEventDetails)taskInstance.TriggerDetails;
switch (notifyData.NotificationType)
{
case NetworkOperatorEventMessageType.Gsm: // 0
break;
case NetworkOperatorEventMessageType.Cdma: // 1
break;
case NetworkOperatorEventMessageType.Ussd: // 2
break;
case NetworkOperatorEventMessageType.DataPlanThresholdReached: // 3
break;
case NetworkOperatorEventMessageType.DataPlanReset: //4
break;
case NetworkOperatorEventMessageType.DataPlanDeleted: //5
break;
case NetworkOperatorEventMessageType.ProfileConnected: //6
break;
case NetworkOperatorEventMessageType.ProfileDisconnected: //7
break;
case NetworkOperatorEventMessageType.RegisteredRoaming: //8
break;
case NetworkOperatorEventMessageType.RegisteredHome: ///9
break;
case NetworkOperatorEventMessageType.TetheringEntitlementCheck: //10
break;
default:
break;
}
// Add code to save the message to app local storage, and optionally show toast notification and
tile updates.
}
}
}
JavaScript
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
switch (details.notificationType) {
case networkOperatorEventType.gsm:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.cdma:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.ussd:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
//
// A JavaScript background task must call close when it is done.
//
close();
}
catch (exception) {
// Display error message.
close();
}
The following code shows how to display a toast notification in a background task handle:
JavaScript
var temp = "the parameter will pass to app when app activated from tap Toast ";
toastXml.selectSingleNode("/toast").setAttribute("launch", temp);
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
try {
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;
The following code demonstrates how to retrieve the message stored by the background task handler in the
app:
JavaScript
function activated(eventArgs)
{
if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.launch)
{
if (!eventArgs.detail.arguments)
{
// Initialize logic for the Start experience here.
}
else
{
// Initialize logic for the Notification experience here.
}
}
}
//
// Handle background task completion.
private void OnCompleted(IBackgroundTaskRegistration sender, BackgroundTaskCompletedEventArgs e)
{
var taskCompletion = task as IBackgroundTaskRegistration;
var completionArgs = args.Context as BackgroundTaskCompletedEventArgs;
//
// If the background task threw an exception, display the exception in the error text box.
if (completionArgs.Status != null)
{
throw completionArgs.Status;
}
}
JavaScript
var iter = Windows.ApplicationModel.Background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === “MobileOperatorNotificationHandler”) {
cur.addEventListener("progress", new ProgressHandler(cur).onProgress);
cur.addEventListener("completed", new CompleteHandler(cur).onCompleted);
}
hascur = iter.moveNext();
}
//
// Handle background task progress.
//
function ProgressHandler(task) {
this.onProgress = function (args) {
try {
var progress = "Progress: " + args.progress + "%";
} catch (ex) {
displayError(ex);
}
};
}
//
// Handle background task completion.
//
function CompleteHandler(task) {
this.onCompleted = function (args) {
try {
var key = task.taskId;
} catch (ex) {
displayError(ex);
}
};
}
Troubleshooting
Use these sections to help troubleshoot issues that may come up.
Trigger metadata parsing to register background tasks
For users, when the mobile broadband device is connected, Windows 8, Windows 8.1, and Windows 10
automatically installs the mobile broadband app and associated service metadata and registers background
tasks that are defined in the service metadata. However, in Windows 8.1, the app is not automatically pinned to
the Start screen.
Developers can manually trigger Windows 8, Windows 8.1, and Windows 10 to parse service metadata and
register background tasks by pressing the F5 key (or right-click and select Refresh ) in the Devices and
Printers window on the desktop. Background task registration through service metadata parsing succeeds only
when the app is deployed.
Verify that background tasks are correctly registered
Developers can verify that the Device Setup Manager (DSM) has properly parsed the service metadata by
viewing the event logs under Application and Ser vices
Logs\Microsoft\Windows\DeviceSetupManager .
1. Open Event Viewer.
2. On the Menu tab, select View , and then click Show Analytic and Debug Logs .
3. Browse to Applications and Ser vices Logs\Microsoft\Windows\DeviceSetupManager .
Events of interest include Event ID 220 that indicates that DSM has successfully registered the background task
for the MobileOperatorNotification event, and Event ID 7900, which indicates any errors that are found in the
metadata package.
Verify that provisioning metadata is successfully applied
When applying provisioning metadata, verify that
ProvisionFromXmlDocumentResults.AllElementsProvisioned is true. If not, check the
ProvisionResultsXml for more details about the error. Common mobile broadband errors include the following:
A mismatch between the SIM in the PC and the provisioning file (profile fails with ERROR_NOT_FOUND).
A mismatch between the CarrierId in the provisioning file and the service number in the experience
metadata.
Verify that background tasks are being run by the System Event Broker
You can verify that Windows is generating the MobileOperatorNotification event and that the app’s background
task is being run by the event broker by checking the Event Viewer. Logging for these events is off by default
and can be enabled by performing the following steps:
1. Open Event Viewer.
2. On the Menu tab, select View , and then click Show Analytic and Debug Logs .
3. Browse to Applications and Ser vices Logs\Microsoft\Windows\BackgroundTaskInfrastructure .
4. Right-click Diagnostic log and select Enable Log .
After you enable the logs, a successful execution of the background task results in an event of Event ID = 1 that
has the following description: “An instance of a background task with entry point
<background_task_namespace_name>.<background_task_class_name> and name
MobileOperatorNotificationHandler has been created in session 1 and given an ID of {11111111-1111-1111-
1111-111111111111}.”
If the background task is not being run, first verify that the names of your background tasks that are specified in
the service metadata match the names in the AppXManifest.xml file of your package. Verify that after deploying
the app, parsing the service metadata is triggered and inserts the mobile broadband device.
Verify that Windows receives SMS and USSD notifications
You can verify that Windows is receiving SMS and USSD notifications by checking for SmsRouter events in Event
Viewer.
In Event Viewer, under Application and Ser vices Logs\Microsoft\Windows \Mobile-Broadband-
Experience-SmsRouter\Microsoft-Windows-SMSRouter , are entries such as “The SMSRouter received a
SMS Operator Notification message” and “The SMSRouter received a Text message”. Under Application and
Ser vices Logs\Microsoft\Windows \Mobile-Broadband-Experience-SmsApi\SMSApi are entries such
as “App: Microsoft.SDKSamples.SmsSendReceive sent SMS text message on mobile broadband device:
{11111111-1111-1111-1111-111111111111}”.
Received SMS messages are not detected as operator notifications
If received SMS are not detected as operator notifications, verify the custom filtering rules for administrative
SMS notifications in the account provisioning metadata. For more info about provisioning metadata, see
Account provisioning.
In particular, if account provisioning metadata specifies the sender phone number, verify that the number
formatting specified matches that in the received message by using the SMS APIs. To verify that this is matching
correctly, temporarily change the Pattern to [^]\ * to match all messages from this sender.
Sample backgroundtask.js file
//
// A JavaScript background task runs a specified JavaScript file.
//
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
var details = backgroundTaskInstance.triggerDetails;
switch (details.notificationType) {
case networkOperatorEventType.gsm:
var textMessage = new
Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(details.smsMessage);
showToast("Gsm Msg From: " + textMessage.from + "; TimeStamp: " + textMessage.timestamp,
details.message);
break;
case networkOperatorEventType.cdma:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.ussd:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
taskSucceeded();
}
catch (exception) {
taskFailed();
}
//
// Pass to app through eventArguments.arguments.
//
var temp = "\"Title\"" + ":" + "\"" + title + "\"" + "," + "\"Message\"" + ":" + "\"" + body + "\"";
if (temp.length > 251) {
temp = temp.substring(0, 251);
}
toastXml.selectSingleNode("/toast").setAttribute("launch", "'{" + temp + "}'");
//
// This function is called when the background task is completed successfully.
//
function taskSucceeded() {
//
// Use the succeeded property to indicate that this background task completed successfully.
//
backgroundTaskInstance.succeeded = true;
backgroundTask.taskInstance.progress = 100;
console.log("Background " + backgroundTask.taskInstance.task.name + " Completed");
//
// Write to localSettings to indicate that this background task completed.
//
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Completed";
//
// A JavaScript background task must call close when it is done.
//
close();
}
//
// If the task was canceled or failed, stop the background task.
//
function taskFailed() {
console.log("Background " + backgroundTask.taskInstance.task.name + " Failed");
backgroundTaskInstance.succeeded = false;
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Failed";
close();
}
})();
Related topics
Enabling mobile operator notifications and system events
Creating and configuring Internet Sharing experiences
Mobile operator notification event technical details
4/13/2022 • 8 minutes to read • Edit Online
This topic explains the technical details of a mobile operator notification event.
Event payload
Register for the MobileOperatorNotification event by using metadata
Define filtering rules in provisioning XML
Event payload
The MobileOperatorNotification event payload includes the following fields:
The MobileOperatorNotification event enables each of the scenarios that are described in Mobile operator
notification scenarios by differentiating them by using the MessageType field in the event payload. The
MessageType s are enumerated as follows:
EN UM ERAT IO N TYPE
0 GSM SMS
1 CDMA SMS
2 USSD
3 DataPlanThresholdReached
4 DataPlanReset
5 DataPlanDeleted
6 ProfileConnected
EN UM ERAT IO N TYPE
7 ProfileDisconnected
8 RegisteredRoaming
9 RegisteredHome
10 TetheringEntitlementCheck
The work item that is associated with the MobileOperatorNotification event should start with logic that
effectively differentiate the MessageType , and runs the appropriate code for each scenario.
GSM/CDMA SMS and USSD
An incoming operator message, including SMS and USSD, triggers the MobileOperatorNotification event
together with the appropriate corresponding MessageType s. Unique to these types are EncodingType ,
MessageDataSize , and Message .
DataPlanThresholdReached
By default, this message type is disabled. You can enable it by using provisioning metadata to specify the
DataUsageInMobileOperatorNotificationEnabled field, as shown here.
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{2c85b76b-f859-47c4-8122-721fe8b6c25f}</CarrierId>
<SubscriberId>012345678901234</SubscriberId>
</Global>
<MBNProfiles>
<DefaultProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<Name>Contoso</Name>
<AssociatedPlan>SamplePlan</AssociatedPlan>
<Context>
<AccessString>Contoso.com</AccessString>
<UserLogonCred>
<UserName>User</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
<Plans>
<Plan xmlns="http://www.microsoft.com/networking/CarrierControl/Plans/v1" Name="SamplePlan">
<Description PlanType="Fixed">
<DataLimitInMegabytes>500</DataLimitInMegabytes>
<DataUsageInMobileOperatorNotificationEnabled>true</DataUsageInMobileOperatorNotificationEnabled>
</Description>
</Plan>
</Plans>
</CarrierProvisioning>
For more info about account provisioning metadata, see Account provisioning.
The event is generated with this MessageType when the local data counters estimate that usage (bytes sent
and received) on the mobile broadband interface has changed by 5% since the last occurrence, except in the
following cases:
1. When connected to a home network (non-roaming), if the data plan limit has not been specified, this
event is triggered at every 100 MB of local data usage.
2. When connected to a roaming network, the data plan limit does not apply and this event is triggered at
every 5 MB of local data usage.
The local data counters in Windows 8 are updated every one minute; at most, this event is generated one time
per minute in all described scenarios. In Windows 8.1 the event is delivered in real-time when the 5% threshold
has been reached.
NOTE
Although this information is a good first-order guide, Windows cannot account for unbilled traffic or for usage on other
devices that share the same data limits (such as family plans or SIM-swapping). Mobile operator apps should use local
data counters only to approximate usage since the last sync with the operator’s own billing system. For data usage that
has already been processed, the billing system should be considered authoritative.
DataPlanReset
On the plan reset date, the Data Usage and Subscription Manager (DUSM) resets the user’s current local data
usage to zero.
DataPlanDeleted
For pre-paid data plans that have a fixed expiration date, the DUSM deletes the connection profile that is
associated with the account on the expiration date and the MobileOperatorNotification event is triggered by
using this MessageType . When the connection profile is deleted, Windows Connection Manager no longer tries
to automatically connect to the network that is described by the connection profile.
ProfileConnected and ProfileDisconnected
The MobileOperatorNotification event is generated with these MessageType s when Windows Connection
Manager connects to the network profile that is provided by the operator experience metadata. This event is
triggered on every connect and disconnect, including the initial connection that follows a sleep/resume. It is also
triggered if the device is already connected when the app and service metadata are downloaded and installed.
The ProfileConnected MessageType is triggered on L2 connectivity for the mobile broadband interface.
NOTE
This trigger occurs before network identification is complete. The NetworkStatusChanged event (part of the
NetworkInformation API) is generated when network identification determines the connectivity level of the network.
For more information about network identification, see Quickstart: Retrieving network connection information and the
NetworkInformation class.
<DeviceCompanionApplications>
<Package>
<Identity Name="MyOperatorNotification" Publisher="MyCorporation " />
<Applications>
<Application Id="MyOperatorNotification" />
<DeviceNotificationHandlers>
<DeviceNotificationHandler EventID="MobileOperatorNotificationHandler"
EventAsset="backgroundtask.js" />
</DeviceNotificationHandlers>
</Applications>
</Package>
</DeviceCompanionApplications>
The EventID attribute tells the system what kind of event to expect from the device. The value of the
EventAsset attribute should point to the entry point that implements the background task. This will tell the
system which task to run when that particular event has occurred.
Using this example, the system creates and registers an event that is specific to that device. It also registers the
mobile broadband app for this event. The app must have a JavaScript file called backgroundtask.js that is run by
the system each time that it receives an operator notification.
If the mobile broadband app is written in C#, the event asset must point to the runtime class that implements
the backgroundtask interface.
<DeviceNotificationHandlers>
<DeviceNotificationHandler EventID="MobileOperatorNotificationHandler"
EventAsset="MNOMessageBackground.OperatorNotification" />
When the service metadata and app are downloaded, the Device Setup Manager registers the appropriate work
item with the System Event Broker before the app is run. Immediately after the work item is registered, if the
mobile broadband device is registered or connected to the network, the MobileOperatorNotification event is
triggered together with the corresponding MessageType .
Change background task registration in metadata
If the background task entry point is changed in an updated version of the mobile broadband app, the
DeviceNotificationHandler element in the service metadata must also be changed.
Service metadata is updated automatically on computers running Windows 8, Windows 8.1, and Windows 10.
Mobile broadband apps are updated in the Microsoft Store. You should avoid changing the
DeviceNotificationHandler background task registration in service metadata. If a change is required, the service
metadata should contain references to all the different background task entry points used in all your supported
versions of the mobile broadband app to preserve functionality for users who haven’t updated the mobile
broadband app.
Define filtering rules in provisioning XML
Windows accepts an XML-based provisioning file from you. A sample version of the provisioning XML is shown
here:
For more info about account provisioning metadata, see Account provisioning.
The rules to identify a text message as an operator message can be defined in this XML.
Allowed sender The Sender attribute specifies the reserved sender address from which the notification
is allowed to arrive. (This number must exactly match the sender number that is received in the SMS
message, including the international format).
Pattern The regular expression to identify and optionally extract the data fields from the text message. To
match all messages from a sender, use pattern [^]* .
Related topics
Enabling mobile operator notifications and system events
Creating and configuring Internet Sharing experiences
Mobile operator notification scenarios
4/13/2022 • 6 minutes to read • Edit Online
This topic explains that scenarios when you would use a mobile operator notification with your mobile
broadband app.
Connect to and disconnect from mobile broadband
Network operator messages
Triggering data usage and roaming notifications locally
Data plan expiration and usage reset
Entitlement check for Internet Sharing
Related topics
Enabling mobile operator notifications and system events
Creating and configuring Internet Sharing experiences
Introduction to integrating Windows with wireless
hotspots
4/13/2022 • 2 minutes to read • Edit Online
Wi-Fi hotspots have proliferated in public areas such as airports, coffee shops, and hotels. Operators of such
networks generally offer Internet access, either as a complimentary service to their clients that is funded by the
venue owner, or as a paid offering.
Various methods have been developed to handle authentication to these networks. Open networks that have
captive portals (called the “Universal Access Method” in Wireless Internet Service Provider roaming [WISPr]) are
the common denominator, as they are accessible to users on any device that has a WLAN interface and a web
browser. However, captive portal extensions (WISPr) and alternate authentication methods (Hotspot 2.0, EAP)
offer opportunities to streamline the hotspot connection experience.
The topics in this section address the interaction between a Wi-Fi hotspot operator, their app, and Windows 8,
Windows 8.1, orWindows 10. The described actions can be taken by a standard app that is downloaded from the
Microsoft Store, or by a mobile broadband app that is installed by Windows to complement a mobile broadband
device that is attached to the computer.
Get started with a hotspot authentication app
Hotspot authentication methods
Related topics
Mobile operator scenarios
Review the hotspot authentication sample
4/13/2022 • 2 minutes to read • Edit Online
The Hotspot Authentication Sample demonstrates the application of a provisioning file and how it handles a
hotspot authentication event. This sample does not run with privileged APIs; it demonstrates the application of
signed provisioning metadata.
For an example of how to use unsigned provisioning metadata together with privilege APIs, see the Mobile
Broadband Provisioning sample.
Related topics
Integrating Windows with wireless hotspots
Update the hotspot authentication sample
4/13/2022 • 2 minutes to read • Edit Online
The Hotspot Authentication Sample project uses a default carrier ID and application family name. To use the
sample in your own test environment, you must change the following items:
Update your Carrier ID If you are publishing a mobile broadband app, this should be the Experience ID
that is associated with your app and service metadata. If you are a Wi-Fi-only operator, generate a new
GUID to use as your company’s ID.
Update the SSID The SSID that you use for test should match the SSID in the provisioning file and must
offer captive portal and WISPr challenge to connecting clients.
Sign the provisioning file If you are a Wi-Fi-only operator, you must sign the provisioning file. In the
Windows 8 SDK or the Windows 8.1 SDK, find the tool ProvisioningTestHelper.psd1 . Import this into a
PowerShell session to add the following four additional cmdlets:
Install-TestEVCer t Generates a new CA certificate, registers it on your test machine as a trusted
EV SSL provider, and uses it to generate and sign an EV certificate for use in signing.
Conver tTo-SignedXml Uses an EV certificate (generated for test, or issued by a third-party
provider) to apply an XML-DSig signature to a Provisioning Metadata XML file. This signature from
a trusted certificate causes Windows to accept the provisioning file as valid from a mobile
broadband app that has no affiliated hardware.
Test-SignedXml Checks a provisioning file to ensure schema conformance and valid signature.
Install-RootCer tFromFile Applies the test root certificate on a different PC, to test the client
experience on a machine other than the development PC.
Related topics
Get started with a hotspot authentication app
Verify background events
4/13/2022 • 2 minutes to read • Edit Online
After you connect to your hotspot network, check that the background event is launched. If not, check the
following:
Did Windows detect your hotspot? If so, the network list should indicate a limited connection. If
Windows detects connectivity to the Internet after connecting to the network, no hotspot authentication
actions are taken.
Did Windows detect WISPr on your hotspot? If so, the background event will fire or the user will be
prompted for credentials. If Windows opens the browser instead, WISPr was not detected. Check that the
XML message is present in the browser’s redirect page and that it conforms to the WISPr specification.
Is your app correctly associated with the profile? If so, the background event will fire. If not, the
user will be prompted for credentials upon manually connecting to the network. Check that the
application family name specified as the ExtensionId matches your application and that provisioning was
successful.
Next, check that you can successfully authenticate to the network. In particular, you should cover the following
cases:
Successful authentication In the ideal case, your app can provide credentials and connect the user to
the network.
User interaction If you need to interact with the user in certain cases, ensure that your app launches to
the correct context to perform the interaction, and not simply to your app’s home page.
Unsuccessful authentication Particularly when using prefixes, you should handle the possibility that a
network matches your prefix, but that you cannot generate credentials for it. In this case, you should stop
authentication.
Access denied In certain cases, your app will receive the background event, but might not be able to
retrieve the details of the authentication attempt. In this case, your background event should stop cleanly
as soon as possible.
Related topics
Get started with a hotspot authentication app
Captive portals
4/13/2022 • 3 minutes to read • Edit Online
Most hotspots implement customer interaction by using a captive portal, which is a restricted network
connection in which all client HTTP requests are redirected to the provider’s web site. The web site can then
prompt users to agree to the operator’s terms and conditions, enter payment information, or enter credentials
to verify prior payment arrangements.
Several problems exist by using such an experience:
Other applications (such as email clients) are also redirected. If the user tries to use an app other than the
web browser first, they will encounter errors without knowing how to resolve them.
If the initial connection attempted is made over Secure Sockets Layer (SSL), the browser displays a
security warning to the user before the user is redirected to the captive portal. This creates a confusing
experience for users because they must ignore the security warning to get connected.
Windows supports captive portal networks by immediately opening the web browser if a captive portal is
detected. The user sees your branded web page in the foreground of their device, which helps them to
understand what actions they should take to authenticate by using the captive portal.
Windows provides mechanisms that can let users bypass captive portals on subsequent connection attempts.
However, the captive portal is always the experience that is encountered by a first-time user.
This topic discusses the following best practices for using captive portals:
Consistent connection handling
Touch-friendly web pages
Provision after purchase
Offer app installation
Related topics
Hotspot authentication methods
WISPr authentication overview
4/13/2022 • 2 minutes to read • Edit Online
A Wireless Internet Service Provider roaming (WISPr)-capable hotspot includes a payload in its captive portal
page that is similar to the following:
<HTML>
<!--
<?xml version=”1.0” encoding=”UTF-8”?>
<WISPAccessGatewayParam xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:noNamespaceSchemaLocation=”http://www.acmewisp.com/WISPAccessGatewayParam.xsd”>
<Redirect>
<AccessProcedure>1.0</AccessProcedure>
<AccessLocation>Hotel Contoso Guest Network</AccessLocation>
<LocationName>Hotel Contoso</LocationName>
<LoginURL>https://captiveportal.com/login</LoginURL>
<MessageType>100</MessageType>
<ResponseCode>0</ResponseCode>
</Redirect>
</WISPAccessGatewayParam>
-->
</HTML>
A smart client, such as Windows, interprets this XML (which is contained in an HTML comment to avoid its
display to customers), to learn where the user’s credentials must be submitted.
When a customer manually connects to a WISPr-capable network, they see the following prompt:
Customers who select No, I need to sign up are directed to your captive portal. Customers who select Yes,
I’ll enter my user name and password are prompted to enter their credentials. These credentials are
provided to your website, and the user is connected after successfully authentication.
A mobile broadband app can automatically supply credentials or replace the credentials prompt by using a
tailored purchase or authentication flow. This requires that the network support WISPr, and that the app be
installed before the user connects to the network.
If your network offers WISPr to clients by using certain UserAgent strings, the user will not see this prompt and
cannot manually enter credentials. However, your app can still participate in WISPr authentication by including
the appropriate UserAgent when it creates the network profile.
The following topics are included in this section:
Provisioning for hotspot authentication
Handling large numbers of SSIDs
Handling the hotspot authentication event
Provisioning for hotspot authentication
4/13/2022 • 2 minutes to read • Edit Online
For an app to participate in the hotspot authentication process, it must first create one or more profiles for Wi-Fi
hotspots. This is done by using the Provisioning Agent interface that is discussed in Using metadata to configure
mobile broadband experiences. The hotspot must use open authentication and must include the
HotspotProfile element. The following provisioning file sample shows how to associate an SSID with your app:
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>Contoso Wi-Fi</name>
<SSIDConfig>
<SSID>
<name>Contoso Wi-Fi___33</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
<HotspotProfile xmlns="http://www.microsoft.com/networking/WLAN/HotspotProfile/v1">
<ExtAuth>
<ExtensionId>YourAppIdGoesHere</ExtensionId>
</ExtAuth>
<TrustedDomains>
<TrustedDomain>www.mycaptiveportal.com</TrustedDomain>
</TrustedDomains>
<UserAgent>contoso</UserAgent>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
The ExtensionId field contains the package family name of the app that generates hotspot credentials. The
package family name is automatically generated by Visual Studio. To find the package family name for your
application, open the package.appxmanifest file in your Visual Studio solution and go to the Packaging
window.
After the provisioning file is processed, the app that has the package family name “YourAppIdGoesHere” must
register for the Hotspot Authentication event. It is required that the provisioning file is processed first to grant
the specified app access to this event. An app can register a single handler for this event. The event registration
remains valid as long as there is at least one profile that refers to the corresponding app.
No, Wi-Fi provider Mobile broadband app or Certificate must: User is prompted to
web site - Chain back to trusted root confirm the first time the
CA certificate is used; none
- Be marked for Extended thereafter.
Validation
Related topics
WISPr authentication
Handling large numbers of SSIDs
4/13/2022 • 2 minutes to read • Edit Online
This topic describes ways to handle the requirement for large numbers of SSIDs.
Windows 8.1 and Windows 10 significantly improve support for a large number of SSIDs by increasing the
amount of SSIDs that can be configured in a single WLAN profile. A WLAN profile can now contain up to 10,000
SSIDs. Additionally, WLAN profiles support SSID prefixes.
The following sections are included in this topic:
Multiple SSIDs per profile
Secondary SSIDs
Prefixes
Example profile
Secondary SSIDs
Windows 8 introduced the concept of secondary SSIDs inside the HotspotAuth section of the WLAN profile to
extend the amount of SSIDs that are covered by a profile. This is still supported in Windows 8.1 and
Windows 10, but we recommend using the SSID section of the WLAN profile instead to support auto-connect
scenarios.
To configure more than 25 SSIDs per profile in Windows 8, you can specify secondary SSIDs for each profile in
the SSIDConfig note of the HotspotAuth section. This does not create additional profiles for these networks, but
associates the Hotspot settings from the profile together with that SSID.
If the user manually connects in the future and creates a new profile, the hotspot settings from this profile are
automatically associated with the user-created profile. Because secondary SSIDs do not auto connect unless the
user manually connects to them one time, these should be less common networks that most users do not
encounter.
You can have a maximum of 250 secondary SSIDs per profile.
Prefixes
To associate with a particularly large or dynamic set of SSIDs, the SSID list can contain prefixes in addition to
static SSIDs. This allows you to associate your mobile broadband app with a broad set of SSIDs that have four or
more octets in common at the beginning of the SSID.
In Windows 8, SSID prefixes are supported in the secondary SSID list only. In Windows 8.1 and Windows 10,
SSID prefixes are supported in the SSIDConfig section of the WLAN profile using the v2 namespace.
Example profile
This section shows an example profile containing an SSID in the v1 and v2 namespace each as well as an SSID
prefix.
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1"
xmlns:v2="http://www.microsoft.com/networking/CarrierControl/WLAN/v2">
<name>SampleProfile</name>
<SSIDConfig>
<SSID>
<name>MySSID1</name>
</SSID>
<v2:SSID>
<v2:name>MySSID2</v2:name>
</v2:SSID>
<v2:SSIDPrefix>
<v2:name>MySSIDPrefix</v2:name>
</v2:SSIDPrefix>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
</security>
</MSM>
</WLANProfile>
Related topics
WISPr authentication
Handling the hotspot authentication event
4/13/2022 • 4 minutes to read • Edit Online
Windows 8, Windows 8.1, and Windows 10 trigger the hotspot authentication event when it detects a captive
portal that supports Wireless Internet Service Provider roaming (WISPr).
When the event occurs, the receiving app must immediately call the
Windows.Networking.NetworkOperator.HotspotAuthentication.Tr yGetAuthenticationContext
function by using the event token that is provided as an argument to the event handler. This function returns an
object that manages the hotspot authentication attempt. In the event that the function fails, the event handler
must exit without performing any additional actions.
Properties on the object allow your app to retrieve the following items:
The SSID of the wireless network.
Details about the network adapter that is connected to the hotspot.
The URL that contains the WISPr message.
The XML payload of the WISPr message.
The authentication URL to which credentials are supplied.
Other APIs exist to retrieve the following items:
The BSSID of the wireless network (see Windows.Networking.Connectivity namespace ).
DHCP parameters of the network (see Win32 and COM for UWP apps).
By using this information and any other information that your app needs to obtain from the local system or the
network, credentials can be generated. The object also contains methods that permit the app to continue or
complete the hotspot authentication.
The following sections are available in this topic:
Issue credentials
Abort authentication
Use alternate authentication methods
Interact with the user
Issue credentials
In the simplest case, the app generates credentials based on information it has or can retrieve. For example, a
username and password are generated by using information in the WISPr payload and information about the
network adapter.
After performing any actions necessary to generate or obtain credentials, the app calls the IssueCredentials
method on the HotspotAuthenticationContext object. This method permits the app to supply the following:
The WISPr UserName parameter
The WISPr Password parameter
Arbitrary non-standard parameters to include in the WISPr response
Behavior on failure
If the server rejects the credentials supplied by the app, Windows disconnects from the network and does not
retry a connection in the current user session. The final flag allows the application to indicate that if the
credentials are unsuccessful, Windows should never automatically retry a connection by using this profile.
There are two variations of this API. The IssueCredentials method passes the parameters to Windows and then
returns instantly. This API does not provide the outcome of the authentication attempt. The
IssueCredentialsAsync method, introduced in Windows 8.1, is an asynchronous version that enables
applications to retrieve the result of the authentication attempt.
Abort authentication
If the app discovers that it cannot generate credentials for the current network (because roaming agreements
have changed, information is unavailable, or for another reason), it must call the Abor tAuthentication method
on the HotspotAuthenticationContext object.
Windows disconnects from the network and does not reattempt a connection in the current user session. This
function accepts a flag that indicates Windows should never automatically retry a connection using this profile.
Note This method does not remove the profile from the system, and the app can be asked for credentials
again if the user manually attempts to connect to the network. If the profile is completely removed, the app
must supply a new provisioning file that removes the associated profile.
Related topics
WISPr authentication
Hotspot 2.0
4/13/2022 • 2 minutes to read • Edit Online
Hotspot 2.0 is a standard for seamless authentication to hotspots. Hotspot 2.0 offers an encrypted connection
between the client and the access point. It uses IEEE 802.11u to communicate with the provider before it
establishes a connection. Authentication and encryption are provided by using WPA2-Enterprise together with
one of several EAP methods.
The following table describes common credential types that are defined by Hotspot 2.0:
O P ERATO R C A N
EA P M ET H O D USER C A N EN T ER P RO VISIO N
C REDEN T IA L EA P M ET H O D SUP P O RT ED C REDEN T IA L S C REDEN T IA L S
*User can select from certificates or the SIM is already present on the system.
Windows 8 and Windows 8.1 do not support the discovery or online sign-up portions of Hotspot 2.0, but they
do support WPA2-Enterprise and all EAP methods that are required by the Hotspot 2.0 specification. Therefore,
Windows 8 and Windows 8.1 can connect to a Hotspot 2.0 network when the user already has credentials.
Because Windows 8 and Windows 8.1 do not support 802.11u discovery, operators must provision Windows 8
or Windows 8.1 with wireless profiles that contain the applicable SSIDs for their networks.
Windows 10 fully supports Hotspot 2.0 Release 1, including discovery and profile creation.
Provisioning Windows using a website
4/13/2022 • 6 minutes to read • Edit Online
This topic describes how to use a web site to let customers purchase and set up a mobile broadband plan on a
computer that is running Windows 8, Windows 8.1, or Windows 10.
For more info about mobile broadband in Windows 8, Windows 8.1, and Windows 10, see Overview of mobile
broadband.
We recommend that you develop and use a mobile broadband app as it provides the most flexibility and creates
the most integrated experience. However, in a few plan purchase and setup scenarios, a mobile broadband app
might not always be installed and available for use. For these scenarios, Windows 8, Windows 8.1, and
Windows 10 include support to automatically open a mobile broadband web site that is hosted by you and
provides the experiences that are required to complete these scenarios.
P RO P ERT Y N A M E P RO P ERT Y VA L UE
SubId Subscriber ID
For GSM devices: IMSI (up to 15 digits)
For CDMA devices: MIN or MIN(IRM) (10 digits)
DevId Device ID
For GSM devices: IMEI (up to 15 digits)
For CDMA devices: ESN (11 digits) or MEID (17
digits)
IMPORTANT
This topic is intended for Microsoft's mobile operator (MO) partners who can configure how Windows connects to their
networks. If you are a customer who is experiencing Windows network connection issues, see Fix network connection
issues in Windows.
NOTE
Windows responds to Ethernet connections but does not automatically manage Ethernet connections.
This topic describes how Windows automatically manages physical wireless connectivity and does not consider
these connections:
Dial-up connections, such as modems
Pure virtual interfaces, such as VPNs and tunneled IP connections
For PCs that have multiple Ethernet ports, Windows cannot prevent an interconnection that is created by
physically connecting the PC to two different Ethernet networks.
Effect on soft disconnect
Because prohibiting interconnections is a security consideration, any disconnections that comply with this policy
take effect immediately, even if there is ongoing activity. Users will experience a connectivity disruption when
transitioning between public and corporate networks, even if the two networks overlap.
For example, a user engaged in a VoIP call over a mobile broadband network with a laptop docked to a
corporate Ethernet connection will lose the call, although the app may be able to automatically recover over the
new connection. If the policy was not enabled, Windows would instead soft-disconnect the mobile broadband
connection by waiting for the call to complete. On the other hand, a VoIP call started over a corporate Wi-Fi
network will not be disrupted when docked to the corporate network because both networks connect to the
domain. The Wi-Fi network is disconnected after the call is completed.
Prohibit roaming on mobile broadband networks
This policy prevents Windows from connecting to mobile broadband networks that are in a roaming state. By
default, this policy is disabled, and the user may choose to manually connect to a mobile broadband network
while roaming or to enable automatically connecting to such a network. When this policy is enabled, the user
cannot choose a roaming mobile broadband network from Connection Manager.
Network preferences
When considering which multiple connections to maintain, Windows uses a number of traits to determine the
preferred networks. This is used only when determining whether to maintain a connection to a given interface,
not for routing. If a connected interface is not in the process of being soft-disconnected, routing is determined
by the metric in the routing table. If the route metric is not specified manually, Windows will automatically
assign a route metric based on the link speed of the adapter.
Connection priorities
Windows prioritizes connections in the following order:
1. Ethernet networks
2. Networks manually connected during the current user session
3. Networks that connect to both the Internet and the Active Directory domain to which the PC is joined
4. Signal strength of the currently connected Wi-Fi network
5. The PC’s preferred network list
Even though the link speed influences routing behavior among currently connected interfaces, Windows does
not make connectivity decisions based on the link speed or throughput of a network. It is not possible to
configure Windows to change its connection preference between a mobile broadband network and a Wi-Fi
network based on the current speed of the mobile broadband network. If both are connected, the user or a
desktop app can change route metrics to influence routing preferences.
Signal strength
For Windows 8 and Windows 8.1, if Windows detects that the currently connected Wi-Fi network has very low
signal strength, it may choose to connect a mobile broadband network (if permitted by policy) to avoid
disrupting network connectivity. This helps to smooth the transition when a user is moving away from a wireless
access point.
Windows does not disconnect a more preferred Wi-Fi network until the signal strength cannot maintain the
connection. If signal strength improves, Windows may soft-disconnect the mobile broadband adapter.
Windows 10 does not use the Wi-Fi signal strength.
Preferred network list
In most situations, the preferred network list determines which wireless network profiles Windows will use to
connect. Prior to Windows 8, this list applied to Wi-Fi networks only. In Windows 8, Windows 8.1, and
Windows 10, it can also include mobile broadband networks.
Automatic generation
Windows 8, Windows 8.1, and Windows 10 automatically update the preferred network list based on user
actions. Any manual connection or disconnection will update the network list so that the same behavior will
occur automatically in the future.
The following user actions modify the preferred network list:
Initially connecting to a network The new network is added to the network list. The user specifies
whether the network will automatically connect in the future.
Connecting to a new Wi-Fi network for the first time makes the network the most preferred
network in the list.
Connecting to a new mobile broadband network for the first time makes the network the least
preferred network in the list.
Manually connecting to a Wi-Fi network Any other Wi-Fi network in range that is higher on the list
is moved below the newly connected network in the list. The user specifies whether the network
automatically connects in the future.
Disconnecting from a network Windows will not automatically connect to this network in the future.
It remains on the network list in case the user modifies this setting in the future.
Group Policy
Wi-Fi profiles created by Group Policy are at the top of the network list. The user may manually disconnect from
these networks or manually connect to other networks, but these networks remain at the highest position on the
network list until removed by Group Policy.
Carrier-provisioning metadata
Mobile broadband and Wi-Fi hotspot operators provide Windows with a series of mobile broadband and Wi-Fi
profiles by using the ProvisioningAgent or msProvisionNetworks APIs.
When initially provisioned, the operator-created profiles are added to the top (Wi-Fi only) or bottom (if mobile
broadband is included) of the existing network list. You cannot influence the position of the networks the user
provisions in the network list. However, you can define the relative order of their networks in the network list.
The user’s actions may modify the network list between applications of provisioning metadata. When
provisioning metadata is reapplied, your desired network order is restored. However, the reordered set of
networks is moved to the lowest position to which the user had moved any of your networks.
The preference between networks in the provisioning metadata is determined by the following:
1. The optional priority attribute on each network profile
2. Media type (Wi-Fi is more preferred than mobile broadband)
3. Order specified in the XML file
Manual modification
Prior to Windows 8, the Wi-Fi preferred network list was accessible to the user through the Manage Wireless
Networks control panel. Telemetry indicates that very few users ever accessed this functionality. Additionally,
this user interface was tied to Wi-Fi only and could not incorporate preferences between Wi-Fi and mobile
broadband.
Most users will not need to manually modify the network list. However, certain users or applications may find it
necessary to do so.
User interface
To remove a profile from the preferred network list while it is in range, select and hold (or right-click) the
network and choose Forget this network . A network that is not in range cannot be removed from the list
through the user interface.
Win32 APIs
An application may create new profiles in the network list using the appropriate media-specific API:
For Wi-Fi networks, use the WlanSetProfile function.
For mobile broadband networks, use the
IMbnConnectionProfileManager ::CreateConnectionProfile method.
To modify the order of the network list, use the WcmSetProfileList function. We do not recommend using the
WlanSetProfileList function, as it may disturb the position of mobile broadband profiles in the network list in
unintended ways.
To delete profiles from the network list, use the appropriate media-specific API:
For Wi-Fi networks, use the WlanDeleteProfile function.
For mobile broadband networks, use the IMbnConnectionProfile::Delete method.
Command-line
A user or script may create new profiles in the network list by using the appropriate media-specific commands:
For Wi-Fi networks, use the netsh wlan add profile command.
For mobile broadband networks, use the netsh mbn add profile command.
The order of the Wi-Fi profiles in the network list may be modified using the netsh wlan set profileorder
command. However, this is not recommended and can disturb the position of mobile broadband profiles in the
list in unintended ways.
To delete profiles from the network list, use the appropriate media-specific commands:
For Wi-Fi networks, use the netsh wlan delete profile command.
For mobile broadband networks, use the netsh mbn delete profile command.
Conflict resolution
When multiple profiles exist for the same network, Windows 8 and Windows 8.1 use the following logic to
determine which profile should be used:
1. Profile Type
a. Group Policy profiles are preferred over user-created profiles.
b. All-user profiles are preferred over single-user profiles.
2. Interface Arrival The profile on the most recently installed interface will be used.
UWP mobile broadband apps overview
4/13/2022 • 3 minutes to read • Edit Online
UWP apps
UWP apps are full-screen or windowed apps that are tailored for the following:
Your users’ needs
The devices that they run
Touch interaction
The Windows user interface
UWP apps are optimized for touch, are aware of the user's location and identity, and are hosted in the Microsoft
Store. UWP apps are always on and available for instant use, and always connected with the latest content from
the web. Users can discover and purchase these apps in the Microsoft Store: the apps can be installed quickly
and uninstalled cleanly.
All UWP apps share the following features and benefits:
Development platforms UWP apps are built by using the Windows Software Development Kit for
Windows 10 and the Windows Runtime APIs.
Programming languages You can build UWP apps by using JavaScript with an HTML and cascading
style sheets (CSS) presentation layer, or by using C++ or C# with an Extensible Application Markup
Language (XAML) presentation layer.
Touch optimization Touch interaction support is built-in. You can design your mobile broadband app
for touch, and Windows gives you keyboard, mouse, and graphical scaling support.
For more info about UWP apps, see Getting started with Windows 10 apps.
IMPORTANT
Your app must optimize for touch input and follow Windows 10 UI design principles. For more info about how to design
the user experience for mobile broadband apps, see Designing the user experience of a mobile broadband app.
UI source code between MBAE and an MO UWP app might differ due to changes between Windows 8/Windows
8.1 and Windows 10 UI principles. Most business logic source code, however, should not require much change.
For example, the code for accessing the back end and accessing mobile broadband information might be the
same. However, MOs should validate each of the Mobile broadband app scenarios accordingly.
Account management
4/13/2022 • 2 minutes to read • Edit Online
After users have purchased a subscription, they can perform following tasks:
View current data usage Users can view their current data usage and understand their billing cycle (or
session end date) to make an appropriate decision on their data usage.
Manage account settings Users can view and securely manage their payment and account details
(such as password, email address, and automatic payment information).
Pay a bill Users can pay their recurring or one-time bill by using your UWP app.
Account management functionality presents a subscriber’s relationship with an operator. You can use this to
create a branded experience that can distinguish your service from competitors’ services.
Design considerations include the following:
Make data usage a combination of local and back-end information To reduce the load on the
back-end servers as much as possible, Windows provides a local Data Usage API that you can use to
combine back-end data usage. You can periodically get the usage information from the back-end and
correlate that with local data usage.
Periodically update Windows with data usage Windows 10 is designed to behave intelligently on
metered networks. This can save significant network capacity because Windows and UWP apps can use
your mobile broadband network for essential traffic. To be more accurate and to include more
information for applications (for example, data limits and usage), Windows relies on you to periodically
provide correct information. Your app can set this information by using Data Usage APIs.
App startup
4/13/2022 • 2 minutes to read • Edit Online
When the mobile broadband app is started, it should check whether Internet access is available. The app can use
an API to discover the various states of Internet connectivity. The app can then determine whether it can access
back-end data when the Internet connection is in a “walled garden” state. If there is no Internet connection, the
app should show an appropriate message or offline experience to the user.
If multiple operators’ subscriber identity modules (SIMs) are attached to the PC, the app can determine this. The
app must present a user interface that works for multiple connected operator devices or accounts.
For example, the app can read the IMSI and IMEI information from the mobile broadband device. This
information can be used as part of the authentication scheme, in addition or in place of a logon screen that
sends user-name and password information to the back-end. Windows provides an API to securely store user-
name and password information that the app can subsequently use for authentication after the first logon
attempt. All user-name and password information must be exchanged with the operator back-end over Secure
HTTP (HTTPS).
Related topics
Mobile broadband app scenarios
Help and support
4/13/2022 • 2 minutes to read • Edit Online
You can reduce customer support calls by providing help and support through your mobile broadband app.
In your app, you can provide access to self-help material in addition to assisted support channels. You can create
a section where the users can find answers to the most common questions. You can simplify the help
information based on a user’s device or firmware.
You can simplify the user experience by showing help for the user’s device only. You can get device model and
firmware information by using the Subscriber and Device Information API.
Related topics
Mobile broadband app scenarios
Hot spot authentication
4/13/2022 • 2 minutes to read • Edit Online
You should offload data traffic to Wi-Fi hot spots whenever possible. Windows Connection Manager can
automatically connect to Wi-Fi networks when they are available. To connect to Wi-Fi networks, you must
provide hotspot credentials to Windows. You can provide hotspot credentials by implementing your own
authentication in the app.
Related topics
Mobile broadband app scenarios
Live tile updates
4/13/2022 • 2 minutes to read • Edit Online
On the Windows 10 Star t menu, tiles are the primary representation of an app. Users start their apps through
those tiles, and the tiles can display new, relevant, and tailored content to the users. You can keep tiles alive with
activity and draw users back into your app repeatedly. You can display information about Premium services, or
any important information that you want to bring to users’ attention.
Related topics
Mobile broadband app scenarios
Notifications
4/13/2022 • 2 minutes to read • Edit Online
You can keep your users informed through service notifications such as plan activation status, approaching data
cap, and currently roaming. Windows supports existing channels such as SMS, USSD, and Windows Notification
Service to trigger notifications.
Your mobile broadband app should communicate time-critical events to the user through toast notifications
whether the user is in another app, on the Star t screen, or on the desktop.
Your app can receive background events to process SMS or USSD notifications. For info about background
notifications that are associated with mobile broadband apps, see these API pages under the
Windows.ApplicationModel.Background namespace:
MobileBroadbandDeviceServiceNotificationTrigger
MobileBroadbandPcoDataChangeTrigger
NetworkOperatorNotificationTrigger
SmsMessageReceivedTrigger
Related topics
Mobile broadband app scenarios
Plan purchase
4/13/2022 • 2 minutes to read • Edit Online
A simple and intuitive on-device plan purchase that is integrated with the Windows experience can simplify the
subscription acquisition process and let users purchase the subscription when they need the mobile
connectivity.
Developing a plan purchase experience involves the following:
Determination of subscription status When the app is started, it should intelligently determine
whether the device has a currently associated plan, and then show the appropriate experience based on
that. For existing users who have no current associated plan, the app can show an Account Management
experience and a Purchase Subscription experience.
To determine the current subscription status, the mobile broadband app can get device and subscription
information from Windows — for example, International Mobile Subscriber Identity (IMSI), Integrated
Circuit Card ID (ICCID), and International Mobile Equipment Identity (IMEI). It can use the connectivity
status of mobile broadband connection to determine whether the user has a plan.
Purchase or top-up experience The purchase business-logic details (such as plan information,
payment, and credit card validation) must be maintained in your app. Windows supports web services or
cellular protocols such as Unstructured Supplementary Service Data (USSD) to interact with your back-
end systems to develop this business logic.
Provisioning After the user has purchased the plan, Windows must provision the device and you must
activate the device in its back-end. Provisioning is defined as configuring a Windows-based computer
with information that is required to connect to a carrier network. This typically occurs after a subscription
purchase. Provisioning information contains mobile broadband profile (access point name [APN], user
name, and password), hot-spot profiles, Wi-Fi credentials, and plan information. Windows can use this
information to automatically connect to your network without any user input.
For more info about provisioning, see Account provisioning.
For some carriers, the activation process on the mobile network is not instantaneous and can take up to ten
minutes. Your app must handle this case elegantly and give a good user experience. The Windows activation
experience should get information about estimated activation time and display that information to the user
during the purchase.
Design considerations include the following:
Simplify the user experience by retrieving device information During a purchase, your business
logic needs device information to show the plans that are available for the device. Your app can get the
information by using the Subscriber and Device Information API; therefore, you don’t have to ask the user
to manually enter this information.
Provide a seamless connection experience by using the Provisioning API After the user has
purchased the plan, you can assign credentials to the subscription. The user must use these credentials
and connectivity parameters to connect to your network. You can use the Provisioning API to provide this
information. The Provisioning Engine will store this information and automatically connect to your
network.
Choose the back-end interaction For purchasing the plan, the user can use limited connectivity,
alternate Internet connectivity (home, coffee shop), or control channel protocols (USSD).
The following flow chart describes how plan purchase works with Windows and UWP apps:
Related topics
Mobile broadband app scenarios
Premium services
4/13/2022 • 2 minutes to read • Edit Online
You can use your mobile broadband app to let users discover and consume additional services.
Related topics
Mobile broadband app scenarios
Introduction to designing the user experience of a
mobile broadband app
4/13/2022 • 2 minutes to read • Edit Online
This topic provides information about how to design UWP mobile broadband apps for Windows 10. It provides
user experience design guidelines to design apps for users to manage their mobile broadband account and
service. It assumes you familiar with mobile broadband technology, Windows mobile broadband networking,
and the Microsoft Store app platform.
The following sections are available in this topic:
Key scenarios
App organization
Additional resources
Key scenarios
The mobile broadband app should include the following key scenarios:
Plan purchase
Purchase a new subscription to data service.
Refill account balance to a plan.
Account management Displays account data and current plan information.
View data usage
Display current data usage and billing cycle information.
Update Windows with the latest data usage.
Notifications Display data usage and other important account and service messages.
Help and Suppor t Display troubleshooting and customer support contact information.
App organization
The following shows how different pages in the app can be organized:
The app has an account overview landing page that provides a summary of a customer’s account and
data usage. It also contains links to other app pages.
From the landing page, end users can visit a hub page to view billing, plans, services, or help and support
details.
Some hub pages lead to task pages and flows, such as a purchase checkout flow.
Tip For prepaid plans, the account overview could directly link to a Make a Payment page for refill scenarios.
For more information about how to design these pages, see the following topics:
Design the landing page of a mobile broadband app
Design branding in a mobile broadband app
Design account balance and usage info in a mobile broadband app
Design messages in a mobile broadband app
Design billing pages in a mobile broadband app
Design purchase flows in a mobile broadband app
Design help and support pages in a mobile broadband app
Design services and goods pages in a mobile broadband app
Integrate a mobile broadband app with other Windows components
Additional resources
Index of UX guidelines for UWP apps
Overview of mobile broadband
Design the landing page of a mobile broadband
app
4/13/2022 • 3 minutes to read • Edit Online
The landing page is the first page that the user sees when they start the mobile broadband app, except for
certain cases that are described in Integrate a mobile broadband app with other Windows components.
The landing page should follow UWP app guidelines for app layout. To encourage simplicity and ease of
navigation, we recommend that you fit all contents of the landing page into a single page. The landing page is
the central hub of your app. Although it is not a primary navigation method or management page, it showcases
your app and its major functionality.
The following sections describe some of the content that you can include in the landing page:
Usage – show an overview or link
Operator messages – show an overview or link
Links to other key pages
App navigation
Operator branding
Quick summary
Additional resources
App navigation
When describing the landing page, it is important to consider navigation within the app. Your app will have
multiple pages that have various purposes. Windows 10 offers the following tools that can be used for
navigation:
Back button The Back button can be used to return to the previous page in the app. For more
information about the Back button styling, see Quickstart: styling controls.
Drop-down affordance with header text The header text can be used as a drop-down affordance for
navigation between multiple pages in an app. In the previous figures, clicking Account Over view would
result in a drop-down list of pages in the app that can be navigated to, as shown in the following figure:
For more information about designing app navigation, see Quickstart: Using single-page navigation and
select element | select object .
Operator branding
You can customize your mobile broadband app to suit your individual branding style. By using numerous
customizations, you can make your app unique and easily recognizable. For more info on how you can brand
your app, see Design branding in a mobile broadband app.
Quick summary
Appropriate design for the landing page
Show information at a glance that users will primarily look for in your app.
Use a simple layout to improve readability.
Follow UWP app guidelines.
Disable the Back button if this is the first time that the user is visiting the app.
Inappropriate design for the landing page
Don’t have scrolling on the landing page. Try to restrict all content to a single page.
Don’t have management functionality on the landing page.
Additional resources
Index of UX guidelines for UWP apps
Adding controls and content
Make great UWP apps
Laying out your UI
Integrate a mobile broadband app with other Windows components
Integrate a mobile broadband app with other Windows components
Related topics
Designing the user experience of a mobile broadband app
Design branding in a mobile broadband app
4/13/2022 • 2 minutes to read • Edit Online
Quick summary
Appropriate design for operator branding:
Use primary and secondary corporate brand colors in your app for backgrounds and fonts.
Use brand icons appropriately to maintain simplicity and follow UWP app design guidelines.
Inappropriate design for operator branding:
Don’t fill up white space with icons and images.
Additional resources
Integrate a mobile broadband app with other Windows components
Integrate a mobile broadband app with other Windows components
Integrate a mobile broadband app with other Windows components
Related topics
Designing the user experience of a mobile broadband app
Design account balance and usage info in a mobile
broadband app
4/13/2022 • 2 minutes to read • Edit Online
Users primarily use your mobile broadband app to view account balance and usage information. This data
should be clearly visible on the app’s home screen.
Quick summary
Appropriate design for displaying account info:
Show relevant account information
Show when data was last updated
Use illustrations, such as charts and graphs, to visualize data
Tip You can implement a bar chart by using a determinate progress bar control, as discussed in Adding
progress controls.
When remaining usage is low, show a link to the Plans page to upgrade the plan
Inappropriate design for displaying account information:
Don’t show a long paragraph of legal disclaimers next to data usage. This can distract users from the main
focus of the account usage section. Instead, show a link to a separate section of the app that has the full legal
disclaimers.
Related topics
Designing the user experience of a mobile broadband app
Design messages in a mobile broadband app
4/13/2022 • 2 minutes to read • Edit Online
Your mobile broadband app is a convenient way to communicate with your customers about important account
information. The app should have a section or link on the home screen where end users can view important
account messages. While important operator messages should be shown as tile and toast notifications, they
should also be shown in app view because of the transient nature of toast notifications and the limited amount
of text that can be shown in a tile notification.
You should not show user-to-user chat text messaging, promotions, and advertisements in the messages section
mixed together with operator notifications and alerts because customers might miss important operator
notifications. You can display promotions and advertisements in the layout of your app and display user-to-user
chat text messages in a separate section of the user interface.
The following table shows some example operator messages and alerts.
International roaming Welcome to the UK. For $5 per day you have 25 MB of
data, and then it's $1 per 1 MB. SMS is $0.49 per msg.
Learn more at www.contoso.com/rates/uk.
Data usage overage You’ve used your entire 4 GB data plan. Overage bills @
$10/GB. Save on more data by upgrading your plan
today in the Plans page.
TYPE EXA M P L E M ESSA GE
Data usage status You’ve used 65% of your 40 GB data plan. Any overage
bills @ $5/GB. Tip: Data is unlimited over Wi-Fi. Learn
more in the Plans page.
Plan expiration Your plan expired on July 1, 2013. Renew your plan by
going to the Plans page.
Quick summary
Appropriate design for showing operator messages:
Include functionality to view a list of all messages received, view full details of a message, and delete a
message.
Show important operator messages in a section of the home screen of the app or on its own page in the
app.
Inappropriate design for showing operator messages:
Don’t show user-to-user chat text messages and promotions and advertisements mixed together with
operator notifications and alerts.
Additional resources
Use ListView to display messages. For more info, see Adding List View, Semantic Zoom, and other data
controls.
Use the app bar control to view and delete messages. For more info, see Guidelines for app bars.
Integrate a mobile broadband app with other Windows components
Related topics
Designing the user experience of a mobile broadband app
Design billing pages in a mobile broadband app
4/13/2022 • 2 minutes to read • Edit Online
You should provide the user with the ability to view a billing summary, billing history, make payments, or
recharge the plan.
The Make a payment form should adhere to form guidelines that are described in Design purchase flows in a
mobile broadband app. This page can be linked to from the Billing page for post-paid plans, and through the
Recharge now button on the landing page for prepaid plans.
Quick summary
Appropriate design for the billing page:
Follow the form guidelines, including left alignment, white space, proper grid alignment, and touch
friendliness.
Use a simple layout to improve readability.
Use vertical scrolling for long forms because this makes it easier to tab and to use the online keyboard.
Make the making payments process a simple experience.
Inappropriate design for the billing page:
Don’t try to fill up white space.
Don’t use an iframe to host the flows. Instead, build flows directly into the app experience.
Don’t make the user wait long times without providing visual feedback.
Don’t link to external sites outside of the app.
Additional resources
For more information about views and layouts: see Choosing a layout.
For more information about Listviews, see Quickstart: Adding a ListView.
For design guidance for error handling, see Laying out your UI.
For accessibility guidance, see Accessibility in UWP apps using C++, C#, or Visual Basic.
For more information about how to use built-in controls, see Adding controls and content.
For touch input guidelines, see Quickstart: Touch input.
Related topics
Designing the user experience of a mobile broadband app
Design purchase flows in a mobile broadband app
4/13/2022 • 2 minutes to read • Edit Online
Your mobile broadband app can include a purchase flow for users to use to purchase plans. For first-time
purchases, support your purchase flow over the web. Here are some standard recommendations for the
purchase flow.
Note Do not use an iframe to host these flows in your app.
1. Show users the plan details and allow them to select a plan before you forwarding them into a complete
purchase flow.
2. You can optionally provide a data breakdown for users to estimate the data that they will require. This can
help the user select the best plan to purchase.
Quick summary
Appropriate design for purchase pages:
Follow the form guidelines, which include left alignment, white space, proper grid alignment, and touch
friendliness.
Use a simple layout to improve readability.
Use vertical scrolling for long forms to make it easier to tab and to use the onscreen keyboard.
Let users review and select plans before you start the purchase flow.
Support purchase over the web and first-time purchase.
Inappropriate design for the purchase, recharge, refill, and billing pages:
Don’t use horizontal scrolling for long forms.
Don’t fill up all the white space.
Don’t use an iframe to host the flows.
Don’t make the user wait a long time without providing visual feedback.
Don’t link to websites outside of the app.
Additional resources
For more information about views and layouts: see Choosing a layout.
For more information about Listviews, see Quickstart: Adding a ListView.
For design guidance for error handling, see Laying out your UI.
For accessibility guidance, see Accessibility in UWP apps using C++, C#, or Visual Basic.
For more information about how to use built-in controls, see Adding controls and content.
For touch input guidelines, see Quickstart: Touch input.
Related topics
Designing the user experience of a mobile broadband app
Design help and support pages in a mobile
broadband app
4/13/2022 • 2 minutes to read • Edit Online
Customers who encounter issues using your mobile broadband service will go to the Help and Support page:
We recommend that you show the following information in the Help and Support section:
Instructions or tutorial videos on how to use the mobile broadband service
FAQs about mobile broadband hardware and service
Online chat with customer support
Customer support telephone number
Hardware and software diagnostics information
Quick summary
Appropriate design for help and support page:
Displaying Help and Support content should not require Internet access. The customer might not have
Internet access because they are having issues connecting to your service.
Inappropriate design for help and support page:
Don’t display links that open a web page in an external web browser.
All help and support content should appear inside the app, and the user shouldn’t have to switch
between apps.
Additional resources
For more information about how to use built-in controls, see Adding controls and content.
Mobile broadband WinRT API overview
Related topics
Designing the user experience of a mobile broadband app
Design services and goods pages in a mobile
broadband app
4/13/2022 • 2 minutes to read • Edit Online
You can use your mobile broadband app to publicize other related services. Use the recommended layouts to
organize various services that you want to promote through the Microsoft Store. An example of service
promotion with an organization into categories is provided here.
Quick summary
Appropriate design for the Services and Goods page:
Follow the grid layout for the services page.
Use pictures and brief headings to describe each service.
Use the Microsoft Store for cross promotion.
Use natural panning and zooming as well as horizontal scrolling.
Inappropriate design for the services page:
Don’t link to external sites outside of the app.
Additional resources
Quickstart: Adding a ListView
Related topics
Designing the user experience of a mobile broadband app
Integrate a mobile broadband app with other
Windows components
4/13/2022 • 5 minutes to read • Edit Online
You can use Windows 10 user interface (UI) surfaces to enhance the overall experience of your mobile
broadband app.
For additional user experience design guidelines for layout, navigation, commanding, animations, touch
interaction, snapping and scaling, contracts and capabilities, tiles and notifications, UI controls, app roaming to
the cloud, and fundamentals, see Index of UX guidelines for UWP apps.
This topic contains the following sections:
App settings
Error user experience
App views
Launch points
Tile and toast notifications
Splash screen
Quick summary
Additional resources
App settings
You can use App settings to include settings for your apps configuration. Some examples of these are as follows:
Sign in and sign out
View and edit the user profile
Change billing address
View and edit payment options
View and set marketing preferences
App views
Your app should be adaptive and be able to fit a number of layouts, including:
Landscape
Portrait
Side by side with another app
Filled
Keyboard up
Note When the touch keyboard is up, make sure that elements such as form fields scroll appropriately.
The following examples show how some pages look when side by side with another app.
Make sure that your app is accessible through app views, including high-contrast mode and screen reader
readiness. For more information about how to make your app accessible, see Accessibility in UWP apps using
JavaScript.
Launch points
Your mobile broadband app is available to users in the All Apps view, in Windows Connection Manager, or
through a toast notification.
Launch from Windows Connection Manager
You can connect to the mobile broadband app by using Windows Connection Manager. Your app should open to
the landing page with account and data usage information. After you are connected, Windows Connection
Manager shows the current account and data usage.
Automatic launch from connection manager during a captive por tal purchase flow
When the user is connected to a captive portal network where web traffic is redirected, Windows provides you
the option to automatically launch their app if it’s installed. The app should open to the Plans page that provides
information on how to purchase Internet access.
Launch app from tile in All Apps view
Your app should support users who have multiple simultaneous accounts (for example, using two external USB
mobile broadband adapters). When your app is launched from a tile, your app should let users select the
account that they want to use.
If your app was suspended or already running, it should show the last page used. If your app wasn’t already
running or suspend information is not available, your app should open to the landing page.
Tile and toast notifications
In the Star t menu, tiles are the primary representation of an app. Users launch their apps through those tiles,
which can display new, relevant, and tailored content through notifications. This makes the Star t menu feel
vibrant, and allows the user to see what's new at a glance. An app can also communicate time-critical events to
the user through toast notifications, whether the user is in another app, on the Star t screen, or on the Desktop.
The methodology to design and deliver toast closely parallels that of tiles, thereby lowering the learning curve.
A toast notification can contain text and images but do not support secondary actions such as buttons. Think of
toast as similar to a Windows balloon notification from the taskbar's notification area. Like balloon notifications,
a toast appears in the lower-right corner of the screen. When a user taps or clicks on the toast, the associated
app is launched in a view that is related to the notification. This is the only mechanism by which one app can
interrupt a user in another app. Toasts can be activated, dismissed, or ignored by the user. The user can disable
all toasts for an app.
A toast notification should be used only for information of high interest to the user and typically involves some
form of user opt-in. It is a good choice for incoming email alerts, IM chat requests, and breaking news. However,
it is very important that when you consider using a toast notification, you realize that, due to its transient nature,
the user might never see it. When using toast notifications for data usage overage or roaming alerts, consider
showing the information on your tile and within your app views in case the end user misses the toast
notification.
Splash screen
You can use splash screen to promote branding. For more info about the splash screen, see Adding a splash
screen.
Quick summary
Appropriate design for operator notifications:
Use both toast and tile notifications to alert users of important and high-interest messages that relate to
the subscriber’s account and service plan.
Customize toast and tile background colors and logo based on your brand guidelines.
Include important SMS or USSD operator notifications and alerts that relate to the subscriber’s account
and service plan directly on the landing page.
Inappropriate design for operator notifications:
Don’t show toast notifications for information that is not real time (such as promotional advertisements).
Don’t show user-to-user chat messages and promotions and advertisements mixed together with
operator notifications and alerts, because end users can miss important operator notifications.
Additional resources
Working with tiles, badges, and toast notifications
Guidelines and checklist for toast notifications
Related topics
Designing the user experience of a mobile broadband app