How to Write Managed Code That Uses the Mobile Broadband API - 1

How to WriteManaged Code That Usesthe Mobile Broadband API

Guidelines for Developers of Managed Code Applications

July 10, 2009

Abstract

This document describes how to write applications inmanaged code that call the mobile broadband API in Windows®7. It provides guidelines for original equipment manufacturers (OEMs) and independent software vendors (ISVs) for calling the mobile broadband API from managed code through the COM interoperability interface.

This documentprovides guidelines and key steps for how to developthird-party mobile broadband applicationsin managed code for Windows 7. It describes the techniques and methods that are used to call the mobile broadband API from managed code applications.

This information applies to the Windows7 operating system.

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

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 Document 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,Visual Studio, and Windows 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
July 10, 2009 / First publication

Contents

Introduction

Overview

Installation Requirements

Calling the Mobile Broadband API from Managed Code

Generating a COM Interop Assembly

Using the Type Library Importer to Create a COM Interop Assembly

Using Visual Studio to Create a COM Interop Assembly

Instantiating the Mobile Broadband API Manager Interfaces

Obtaining the Mobile Broadband API Functional Objects

Obtaining the Mobile Broadband API Interface Objects

Mobile Broadband Operations and Sample Code

Error Handling

Resources

Appendix: C# Signature for the Mobile Broadband API

Introduction

This paper provides guidelines and key steps for software developers on how to calltheWindows® mobile broadband API from applications that they write in managed code.

The audiencefor this paper is software developers who have a good understanding of the following:

  • How to develop applications in managed code.
  • The Windows Component Object Model (COM).
  • The C# programming language.
  • Interoperating with unmanaged code.

In addition, the audience should be familiar with the Windows mobile broadband API and have a good understanding of the following:

  • The mobile broadband API specification.

This specification is an authoritative reference for the interfaces, structures, enumerations, and methods that the mobile broadband API supports.

For more information about the mobile broadband API specification, refer to “Resources” later in this paper.

  • The sample code for using the mobile broadband API.

This sample code shows how to use this API from unmanaged code. However, the approach for using the API from managed code is basically the same as from unmanaged code. This paper describes those areas where the approach is different for managed code.

For more information about the mobile broadband API sample code, refer to “Resources” later in this paper.

Overview

The Windows mobile broadband APIis used to implement connectivity to cellular networks. Third-party application can use this API to control and manage mobile broadband interfaces and connections.

Windows7 supports the mobile broadband API.

Theprogramming interface of the mobile broadband API is COM-based and developed as unmanaged code. However, developers can use the COM interoperability interface to call the API from managed code.

This paper includes the following sections that discuss the various techniques for calling the mobile broadband API from managed code:

  • Installation Requirements

This section discusses the software components that must be installed in both the development and deployment environments.

  • Calling the Mobile Broadband API from Managed Code

This section discusses the required steps to write managed code that calls the mobile broadband API.

  • Resources

This section provides a list of documents that have additional information.

Installation Requirements

To develop managed and unmanaged code that calls the Windows mobile broadband API, you must download and install the following components:

  • The Windows Software Development Kit (SDK) for Windows 7 and the .NET Framework 3.5 Service Pack1, whichmust be installed in the development environment. You can install this software in systems that run Windows XP and later versions of Windows.
  • The Windows 7 operating system (RC or later versions), which must be installed in the deployment environment.

Calling the Mobile Broadband API from Managed Code

Because the Windows mobile broadband API consists of unmanaged COM objects and code, you must do the following to call the API from your managed code:

  • Generate a COM interoperability (interop) assembly.
  • Instantiate the mobile broadband API manager objects.
  • Obtain the mobile broadband API functional objects.
  • Handle errorsthat are returned from calls to the mobile broadband API.

Generating a COM Interop Assembly

COM interop assemblies are a bridge between managed and unmanaged code, and map unmanaged COM object members to equivalent managed members.

The .NET common language runtime (CLR) of managed code requires metadata for all data types, which includes COM data types. This metadata is contained in an interop assembly.

You can produce a COM interop assembly by using the following tools:

  • The Type Library Importer (Tlbimp.exe)
  • Microsoft® Visual Studio®

Using the Type Library Importer to Createa COM Interop Assembly

To create a COM interop assembly by using the Type Library Importer, enter the following code from a command line:

tlbimp /machine:MachineTypeTypeLibName

The command-line parameters are as follows:

  • MachineType

This specifies the target CPU platform for the COM interop assembly. The following are the valid values for this parameter:

  • X86
  • X64
  • Itanium (IA64)
  • TypeLibName

This parameter specifiesthe name of the type library (.tlb) file.

By default, the Type Library Importer produces a COM interop assembly that is named TypeLibName.dll.

The name of the mobile broadband API type library file is Mbnapi.tlb. Versions of this file in the SDK are specific to a CPU platform. Inthe SDK installation directory, which is Program Files\Microsoft SDKsby default, the Mbnapi.tlb files are located in the following subdirectories:

  • The x86 version of Mbnapi.tlbis stored in Windows\v7.0\Lib.
  • The x64 version of Mbnapi.tlbis stored in Windows\v7.0\Lib\x64.
  • The IA64 version of Mbnapi.tlbis stored in Windows\v7.0\Lib\IA64.

Youshould create a COM interop assembly from the CPU-specific version of the Mbnapi.tlb file that is appropriate for the deployment environment of your application.

For example, if your application is targeted for only x64 CPU platforms, you must create the COM interop assembly in the following way:

  • Copy the Mbnapi.tlb file from the SDK’s Windows\v7.0\Lib\x64 directory to your development directory.
  • Enter thefollowingcode from a command line:

tlbimp /machine:x64 Mbnapi.tlb

The COM interop assembly that is created from the Mbnapi.tlb file is namedMbnapi.dll. You must use this file to reference the managed types of the mobile broadband API during the compilation of managed code application.

Note: If the application is built as a 32-bit binary, it can run on both x86 and x64 CPU platforms. On x64 and IA64 CPU platforms, 32-bit applications can run seamlessly because of the support of Windows 32-bit on Windows 64-bit (WOW64) 32-bit emulator. In this case, you must use the x32 version of the Mbnapi.tlb file to create the COM interop assembly.

Using Visual Studioto Create a COM Interop Assembly

If you use Visual Studioto build your managed code application, Visual Studioautomatically creates the COM interop assembly.

You must first register the .tlb file first before you add a reference to it in a Visual Studio project. Otherwise, you might see the following error when you try to add the reference:

“A reference to mbnapi.tlb could not be added. Please make sure that the file can be accessed, and that it is a valid assembly or COM component.”

If your development environment is a computer that is not running Windows 7, you can register the Mnnapi.tlb library by following these steps:

1.Open a command prompt and move to the SDK’s Windows\v7.0\Lib directory by using the cd command.

2.From the commandline, enter the following command:

Regtlibv12Mbnapi.tlb

Note: You are not required to register the .tlb file if your development environment is a computer that is running Windows 7 because the operating system has already registered this file.

The following steps showhow to use Visual Studio to reference the mobile broadband API type library and create the COM interop assembly:

1.Open Visual Studio and create a solution. This example uses the name MyProject for the project. Visual Studio creates a project solution that is named MyProject.sln.

2.Add a reference to the Mbnapi.tlbfile. To do this, follow these steps:

a.Click the Project item in the toolbar,and then click Add Reference from the drop-down menu.

b.From the Add Referencepage, click theBrowse tab.

c.Browse to the Mbnapi.tlbfile in the SDK’s Windows\v7.0\Liband select it. Then, click OK.

As soon asyou have added the reference to the Mbnapi.tlbfile in your project, Visual Studio creates the COM interop assembly.

Important: If you want to build your managed code application to run on both x32, x64, and IA64 CPU platforms, you should not compile your application by using the /platform anycpu setting in Visual Studio. Although this setting does compile the managed code application in a platform-agnostic mode, the application depends on the COM interop assembly that is platform-specific.

Instantiating the Mobile Broadband API Manager Interfaces

Three manager interfaces in the mobile broadband API can be instantiated directly. These manager interfaces provide methods for enumerating objects. They also let the application receive notifications for arrival and removal of objects.

The mobile broadband API manager interfaces are as follows:

  • IMbnConnectionManager, which is also implemented as a COM co-class object that is named MbnConnectionManager.
  • IMbnInterfaceManager, which is also implemented as a COM co-class object that is named MbnInterfaceManager.
  • IMbnConnectionProfileManager, which is also implemented as a COM co-class object that is named MbnConnectionProfileManager.

For more information about these and other mobile broadband API manager interfaces, refer to the “Mobile Broadband API Reference” that is listed in “Resources” later in this document.

The following code example shows how to instantiate a mobile broadband API manager interface:

MbnxxxManager mbnxxxMgr = new MbnxxxManager();

IMbnxxxManager xxxMgr = (IMbnxxxManager) mbnxxxMgr;

Note:None of the other mobile broadband API interface objects can be instantiated directly. Your applicationmustfirst instantiate the manager objects and then use the methodsthat the manager objectssupport to enumerate the required interface objects.

Obtaining the Mobile Broadband API Functional Objects

Every mobile broadband API manager interfaces supports a functional object. You can obtain these objects from the manager interface through the interface’s enumeration method.

The mobile broadband API functional objectsare as follows:

  • IMbnConnection
  • IMbnInterface
  • IMbnConnectionProfile

For more information about mobile broadband API functional objects, refer to the “Mobile Broadband API Reference” that is listed in “Resources” later in this document.

You can obtain all these functional objects in the same manner. For example, the following code example shows how to obtain the IMbnInterfacefunctional object by using the enumeration method of theIMbnConnectionManager interface:

MbnConnectionManager mbnConnectionMgr =

new MbnConnectionManager();

IMbnConnectionManager connMgr =

(IMbnConnectionManager) mbnConnectionMgr;

IMbnConnection[ ] arrConn =

(IMbnConnection[ ])connMgr.GetConnections();

Obtaining the Mobile Broadband API Interface Objects

In unmanaged code, you can obtain various mobile broadband API interface objects by calling the IUnknown::QueryInterfacemethod ofthe IMbnConnection, IMbnInterface, and IMbnConnectionProfile objects.

We highly recommend that you do not call the IUnknown::QueryInterfacemethod in your managed code. Instead, you canobtain the interface object in managed code by typecasting the corresponding interface object from the related functional object.

For example, you can use theIMbnInterface functional object to obtain the IMbnRadio interface. The following code example shows how to obtain this interface through typecasting:

//QI IMbnRadio from IMbnInterface

IMbnRadio radio;

radio = (IMbnRadio) inf;

Mobile Broadband Operations and Sample Code

You can perform three kinds ofmobile broadband operations by using the interface objects from the mobile broadband API:

  • Registeringforevent notifications, such as notification of a change in state of the radio on a mobile broadband device.
  • Asynchronous operations.
  • Synchronous operations.

The following example shows how to register for mobile broadband notifications through managed code:

//register for notifications

//class to keep global variables

Class Global

{

public static IMbnRadio g_IMbnRadio = null;

}

//implement the required IMbnXXXEvents

class RadioEventsSink : IMbnRadioEvents

{

public RadioEventsSink () { }

public void OnRadioStateChange (IMbnRadio newInterface)

{

<code>

}

public void OnSetSoftwareRadioStateComplete(IMbnRadio newInterface,uint requestID, int Status)

{

Global.g_IMbnRadio = newInterface;

<code>

}

}

//instantiate corresponding manager object

MbnInterfaceManager mbnInfMgr = new MbnInterfaceManager();

//1.Get an IConnectionPointContainer interface by typecasting //corresponding manager object.

IConnectionPointContainer icpc =

(IConnectionPointContainer) mbnInfMgr;

//2.Call FindConnectionPoint on the returned interface and pass //corresponding IID_IMbnXXXEvents to riid say //IID_IMbnRadioEvents.

Guid IID_IMbnRadioEvents = typeof(IMbnRadioEvents).GUID;

IConnectionPoint icp;

icpc.FindConnectionPoint(ref IID_IMbnRadioEvents, out icp);

//3.Call Advise on the returned connection point and pass

//object that implements IMbnXXXEvents.

RadioEventsSink radioEvtsSink = new RadioEventsSink();

icp.Advise(radioEvtsSink, out cookie);

The following example shows how to perform asynchronous mobile broadband operationss through managed code:

// asynchronous operation

MbnInterfaceManager mbnInfMgr =

new MbnInterfaceManager();

IMbnInterfaceManager infMgr =

(IMbnInterfaceManager) mbnInfMgr;

string interfaceID = “{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}”;

try

{

//obtain the IMbnInterface passing interfaceID

IMbnInterface inf= infMgr.GetInterface(interfaceID);

}

catch(Exception e)

{

Console.WriteLine(e.Message);

throw e;

}

//QI IMbnRadio from IMbnInterface

IMbnRadio radio;

radio = (IMbnRadio) inf;

MBN_RADIO softwareRadioState = MBN_RADIO.MBN_RADIO_ON;

uint requestID = 0;

try

{

//call SetSoftwareRadioState to set the software radio state

radio.SetSoftwareRadioState(softwareRadioState, out requestID);

Console.WriteLine(“Request for SetSoftwareRadioState is submittedsuccessfully with requestID = “ + requestID);

}

catch(Exception e)

{

Console.WriteLine(e.Message);

throw e;

}

//wait for notifications to arrive

//discard the older radio object and use the newer IMbnRadio //interface obatined in the notification //OnSetSoftwareRadioStateComplete

radio = Global.g_IMbnRadio;

The following example shows how to perform synchronous mobile broadband operations through managed code:

// synchronous operation

MbnConnectionManager mbnConnMgr =

new MbnConnectionManager();

IMbnConnectionManager connMgr =

(IMbnConnectionManager) mbnConnMgr;

try

{

// enumerate the connections using GetConnections

IMbnConnection[] arrConn=

(IMbnConnection[])connMgr.GetConnections();

}

catch(Exception e)

{

Console.WriteLine(e.Message);

throw e;

}

foreach(IMbnConnection conn in arrConn)

{

Console.WriteLine("Connection ID = " + conn.ConnectionID);

}

Error Handling

The functions that themobile broadband API COM interfacesdefine return a HRESULT error code. These error codesare converted into corresponding C# exceptions. The mobile broadband API error codes that cannot be mapped to generalized C# exceptions are returned as “Exception from HRESULT <0xXXXXXXXX>”.