Mobile Broadband Connection Manager Development Guide - 1

Mobile Broadband Connection Manager Development Guide - 1

Mobile Broadband Connection Manager Development Guide

May 28, 2009

Abstract

This paper describes how to write a connection manager (CM)utility thatmanages mobile broadband connections in Windows® 7. It provides guidelines for original equipment manufacturers (OEMs),independent software vendors (ISVs), and mobile network operators (MNOs) to develop their own CM by using the mobile broadband API in Windows7. Through these third-party CMs, vendors can either augment or completely replace the native Windows7 Connection Manager.

This paper is intended to be used as both a tutorial and a reference guide for creating third-party mobile broadband CMs for Windows 7. It describes the development stages and testing methodologies that developersshould follow to createa CM.

This information applies to the Windows7 operating system.

References and resources discussed here are listed at the end of this paper.

The current version of this paper is maintained on the Web at:

Disclaimer: This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

© 2009 Microsoft Corporation. All rights reserved.

Microsoft andWindows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Document History

Date / Change
May 28, 2009 / First publication

Contents

Introduction

Overview

Connection Manager Development Stages

Stage 1: Basic Connectivity Functionality

Stage 1 Testing

Stage 1 Additional Tasks

Stage 2: Handling Changes to Radio State and Signal State

Stage 2 Testing

Stage 2 Additional Tasks

Stage 3: Security Operations That Are Related to PIN and PUK

Stage 3 Testing

Stage 4: SMS Functionality

Reading SMS Messages from a Device

Sending SMS Messages

Reading SMS Messages When They Arrive

Stage 4 Testing

Stage 5: APN Database Integration

Overview of APN Databases

Updating the Device’s Firmware with Provisioned Contexts

Creating Connection Profiles from a Provisioned Context

Stage 5 Testing

Stage 6: Service Activation and Vendor-Specific Operations

Service Activation

Vendor-Specific Operations

Stage 6 Testing

Resources

Introduction

This document describes the methods that developers can use to create either a lightweight or complete connection manager (CM). The target audience for this document is:

• Original equipment manufacturers (OEMs).
• Independent software vendors (ISVs).
• Mobile network operators (MNOs).

This document provides guidelines and testing recommendations for the development process.

Overview

In Windows 7, OEMs, ISVs, or MNOscan provide the following methodsfor users to manage mobile broadband connections:

• Use the native Windows7 Connection Manager.

Users can start this utility by clicking the Network icon in the notification area. This Network icon flyout is also known as the View Available Networksuser interface (VAN UI)

The VAN UI provides a unified connection experience across multiple media types,such asmobile broadband andwireless local area networks (LANs). For mobile broadband connections, the VAN UI implements the most commonly used functionality, which includes the following:

• Creation and configuration of connections profiles. These profiles contain the settings for the access point name (APN) and credentials (username and password) for the user’s subscription.
• The ability to connect to or disconnect from a media connection over a network interface.
• Configuration of the network device to auto-connect under different conditions.
• Security operations that are related to the device’s personal identification number (PIN) and PIN unblocking key (PUK).
• Configuration of the device’s roaming parameters.
• The ability to diagnose errors that are related to connection failures, network errors, and service errors.

• Use a lightweight CMthat an OEM, ISV, or MNO provides.

A lightweight CM augments the native Windows 7 Connection Manager andprovides additionalfeatures that arenot available in the VAN UI.

Developers can create a lightweight CM by using the mobile broadband API. This API has methods that third-party CMs can use to communicate with mobile broadband devices by using the mobile broadband stack in Windows 7.

A lightweightCMthat is built by using this API can work with the VAN UIand provide advanced features that are not supported in the VAN UI. These features include the following:

• Service activation.
• Connection provisioning.
• Support for enhanced security operations beyond PIN1 and PUK support.
• Support for the Short Message Service (SMS).
• APN database integration.

• Use the complete CM that an OEM, ISV, or MNO provides.

This type of CM duplicates all the features of VAN UI and also supports additional features as required.

A developer creates a complete CMby using the mobile broadband API.

A lightweight or completeCM can reliably manage mobile broadband devicesthat have a driver that has been certifiedby the Windows Logo Program (WLP) for Windows 7. Conversely,an OEM, ISV,or MNO can use any mobile broadband device with a logo-certifieddriver when it tests the implementation of its CM.

Connection Manager Development Stages

This section describes the following steps that you must use to develop a CM by using the mobile broadband API in Windows7:

Stage 1: Basic Connectivity Functionality

This step implements the basic ability to connect through a mobile broadband interface.

For more information, refer to “Stage 1: Basic Connectivity Functionality” later in this paper.

Stage 2: Handling Changes to Radio State and Signal State

This step implements the ability to detect and handle changes to the mobile broadband device’s radio and signal state.

For more information, refer to “Stage 2: Handling Changes to Radio State and Signal State” later in this paper.

Stage 3: Security Operations that Are Related to PIN and PUK

This step implements the support of operations that are related to the device’s PIN and PUK.

For more information, refer to “Stage 3: Security Operations that Are Related to PIN and PUK” later in this paper.

Stage 4: SMS Functionality

This step implements the support of SMS operations, including reading and writing SMS messages.

For more information, refer to “Stage 4: SMS Functionality” later in this paper.

NoteIf you are developing a lightweight CM, you can begin development at this stage.

Stage 5: APN Database Integration

This step implements the support for integrating the device’s APN database with the CM.

For more information, refer to “Stage 5: APN Database Integration” later in this paper.

Stage 6: Service Activation and Vendor-Specific Operations

This step implements the support of service activation and vendor-specific operations.

For more information, refer to “Stage 6: Service Activation and Vendor-Specific Operations” later in this paper.

For a complete description of the mobile broadband API, refer to“Mobile Broadband API Reference”in the Windows Driver Kit (WDK).

Stage 1: Basic Connectivity Functionality

Stage 1 involves implementingbasic connectivity functionality. To support basic connectivity, the CM must use the following mobile broadband APIinterfaces:

Interface / Description
IMbnConnection / Provides Connect and Disconnect methods.
IMbnConnectionContext / Provides methods to get and set preprovisioned contexts on the device.
IMbnConnectionEvents / Provides notifications on connection and disconnection completion.
IMbnConnectionManager / Maintains a list of available connections.
IMbnConnectionManagerEvents / Provides notifications that are related to connection arrival and removal.
IMbnConnectionProfile / Provides profile query and update methods.
IMbnConnectionProfileManager / Maintains a list of profiles for a given interface and provides profile creation methods.
IMbnConnectionProfileManagerEvents / Provides connection profile arrival and removal notifications.
IMbnInterface / Provides methods to get interface properties.
IMbnInterfaceManager / Maintains a list of interfaces.
IMbnInterfaceManagerEvents / Provides interface arrival and removal notifications.
IMbnRegistration / Provides information about the registered provider.
IMbnSubscriberInformation / Provides subscription details of the device’s Subscriber Identity Module(SIM).

For a complete description of these methods, refer to“Mobile Broadband API Reference”in the WDK.

For the basic connect and disconnect operations to work properly, the CM performs the following steps:

1.Enumerate the list of all available IMbnInterface interfaces, by using IMbnInterfaceManager::GetInterfaces.

Note:The IMbnInterfaceManager interface must be a COM CoCreated instance.

2.Find the interface of the specific mobile broadband device, by searching through the list of available IMbnInterface interfaces.

3.After finding the given IMbnInterface, call the selected interface’s IMbnInterface::GetSubscriberInformation method to get the IMbnSubscriberInformationinterface.

4.Retrieve the device’s SIM subscription information, such asthe international circuit card identifier (ICCId) orinternational mobile equipment identity (IMSI).This information can be queriedby calling the IMbnSubscriberInformation::GetSubscriberInformation method.

5.Wait for a connection to be available by subscribing to IMbnConnectionManagerEvents notifications.

If registration information is required, call the IMbnInterface::QueryInterface method to acquire an instance of theIMbnRegistrationinterface.

To wait for registration state change notifications, register forIMbnRegistrationEvents notifications.

6.After a connection is available, create a profile XML string that is based on the subscription information or the preprovisioned context from the device. The profile can be created by using theIMbnConnectionProfileManagermethod.

The preprovisioned context from the device can be obtained through the IMbnConnectionContext interface. An instance of this interface is acquired by calling the IMbnInterface::QueryInterface method.

As part of creating a profile, a branding logo or icon can also be added to the profile. For more information on how to add a branding icon, refer to “Customizing Mobile Broadband,”which is available from the Microsoft Connect Web site.

For a complete description of the mobile broadband Profile XML schema, refer to“Mobile Broadband SchemaReference”in the WDK.

7.Subscribe for connection completion notifications through the IMbnConnectionEvents interface. This must be done before the profile is created.

8.Create the profile by calling the IMbnConnectionProfileManager::CreateConnectionProfilemethod. After the profile is created, a connection will be established automatically if one of the following is true:

• The profile’s ConnectionMode XML element is set to “auto”.
• The profile’s ConnectionMode XML element is set to “auto-home”, and the device is currently in the home mobile broadband network.

9.If a connection is not automatically established, establish a connection by using the IMbnConnection interface.

10.Before, during, and after a connection has been established, handle change notifications, such as notification of changes to the registration state. The CM is notified of these events by subscribing to the various mobile broadband events API, such as the IMbnInterfaceEvents and IMbnConnectionEvents interfaces.

After the CM is notified of an event,it should update the connection state accordingly.

Stage 1 Testing

You can test the behavior of the CM by comparing the basic connectivity functionality against the VAN UI in Windows7. You must test and verify the following conditions:

• The registered/home provider name in the VAN UI and the CM are the same at all times, especially before, during, and after a connection.
• If a branding icon is specified, it is rendered correctly and is visible in the VAN UI. If not, the icon is in a format that the UI does not support.

For example, you can display the branding icon by modifying the default connection profile that the VAN UI uses. For more information on this and other methods to display the icon, refer to “Customizing Mobile Broadband,”which is available from the Microsoft Connect Web site.

• The state of the connection that was established through the CMis reflected in the VAN UI and vice versa. In other words, the connection status (connected or disconnected) should be the same in the CM and VAN UI.

Also, after the connection has been established, the profile details should be associated with the connection in the VAN UI.

Stage 1 Additional Tasks

During Stage 1, we recommend that the CM development team identify all custom features that must be implemented as part of Stage 6. Custom features, such as service activation, are those that require customized data to be sent to the device or the MNO.

Stage 2: Handling Changes to Radio State and Signal State

Stage 2 involves implementing support to handle changes to radio and signal states. To support this functionality, the CMmust use the following mobile broadband API interfaces:

Interface / Description
IMbnRadio / Provides methods to get and set software radio.
IMbnRadioEvents / Receives notifications of change in radio state.
IMbnSignal / Provides signal strength information.
IMbnSignalEvents / Receives notifications of change in signal strength.

For a complete description of these methods, refer to“Mobile Broadband API Reference”in the WDK.

To show the signal strength properly, the CMmust do the following:

1.Query the current signal strength as reported by a selected mobile broadband interface by using theIMbnSignal interface.

The IMbnSignal interface is accessed by calling the IMbnInterface::QueryInterface method.

2.Register forsignal state change notifications through theIMbnSignalEventsinterface.

The CM must update the signal strength whenever it receives a notification.

To turn the software radio on or off, the CMmust do the following:

1.Call into the IMbnRadio interface to query the current state of the software radio as reported by a selected mobile broadband interface.

The IMbnRadiointerface is accessed by calling the IMbnInterface::QueryInterface method.

2.Register forradio state change notifications through theIMbnRadioEvents interface.

3.Call into the IMbnRadiointerface to turn the software radio on or off.

4.Wait for notifications through callbacks fromthe IMbnRadioEventsinterface for the completion status of this operation.

To check the status of the hardware radio on the mobile broadbanddevice, the CM can do the following:

1.Call into the IMbnRadio interface to query the current state of hardware radio.

2.Register for radio state change notifications through the IMbnRadioEvents interface.

Note Whenever the status of hardware radio changes, the CM is notified through callbacks from theIMbnRadioEvents interface.

Stage 2 Testing

You must test and verify the following during Stage2:

• At all times, the received signal strength indication (RSSI) values that appear in the VAN UI should be similar to the values that appear in the CM.

The VAN UI displays the signal strength in bands from 1 through 5. The range of the RSSI values and the band in which they belongare given in the following table.

RSSI value range / Band/signal strength
0-5, 99 / No signal
6-11 / 1 (Poor)
12-17 / 2 (Low)
18-23 / 3 (Fair)
24-29 / 4 (Good)
30 onwards / 5 (Excellent)

Note The CMis not required to use the same bands as the VAN UI.

• The VAN UI doesnot show the mobile broadbanddevice as connected when the software radio is turned off. The CM must also show the same connection status.
• At this stage, if the Windows 7 troubleshooter is started on the interface, it should request that the user turn on the software radio.

If the CM shows the radio state as off and the software radio is turned onthrough the Windows 7 troubleshooter, the CM should also display the radio state as on.

Stage 2 Additional Tasks

By this stage, the CM development team should be working closely with MNOs and the IHVs to define the behavior of all of the Stage 6 features and APIs. This includes the format of the data exchanged between the following:

• The CM and the device through the mobile broadband API interfaces that support vendor-specific operations.
• The CM and the applications or Web pages that the MNO provides. Note that this data exchange is through a proprietary interface and not through the mobile broadband API.

Stage 3: Security Operations That Are Related to PIN and PUK

Stage 3 involves implementing support to handle PIN and PUK operations.To support this functionality, the CM must use the following mobile broadband interfaces:

Interface / Description
IMbnPin / Provides methods to perform operations such as Enter, enable, and disableon a particular PIN.
IMbnPinEvents / Receives notifications of PIN operation completion.
IMbnPinManager / Maintains the list of all PINs that the device supports.
IMbnPinManagerEvents / Provides notification when information about PINs is available.

For a complete description of these methods, refer to“Mobile Broadband API Reference” in the WDK.

For operations on the various PINs that the device supports, the CMmust do the following:

1.Register with the IMbnPinManagerEventsinterface for notifications on when the PIN list is available. After the PIN list is available, query the currently supported list of PINs.

2.Call into the IMbnPinManagerinterface to get an IMbnPin instance of a particular PIN type. Register forthe IMbnPinEventsinterface to get notifications on the completion status of PIN operations.