WWAN Toolkit

Programmer’s Reference Manual

Intermec Technologies Corporation Worldwide Headquarters 6001 36th Ave.W. Everett, WA 98203 U.S.A. www.intermec.com The information contained herein is provided solely for the purpose of allowing customers to operate and service Intermec-manufactured equipment and is not to be released, reproduced, or used for any other purpose without written permission of Intermec Technologies Corporation. Information and specifications contained in this document are subject to change without prior notice and do not represent a commitment on the part of Intermec Technologies Corporation. © 2006-2011 by Intermec Technologies Corporation. All rights reserved. The word Intermec, the Intermec logo, Norand, ArciTech, Beverage Routebook, CrossBar, dcBrowser, Duratherm, EasyADC, EasyCoder, EasySet, Fingerprint, INCA (under license), i-gistics, Intellitag, Intellitag Gen2, JANUS, LabelShop, MobileLAN, Picolink, Ready-to-Work, RoutePower, Sabre, ScanPlus, ShopScan, Smart Mobile Computing, SmartSystems, TE 2000, Trakker Antares, and Vista Powered are either trademarks or registered trademarks of Intermec Technologies Corporation. There are U.S. and foreign patents as well as U.S. and foreign patents pending.

ii

WWAN Toolkit Programmer’s Reference Manual

Document Change Record This page records changes to this document. The document was originally released as version -001. Version Number

Date

Description of Change

003

11/2011

This document was updated to: • Remove information for the Connectivity API, which is no longer supported. • Remove information for the 700 Series Mobile Computers. • Include information for the 70 Series Mobile Computers. • Include fuctions for the Flexible Network Radio.

002

9/2009

This document was updated to include information for the CN4 and CN50 Mobile Computers.

001

8/2008

This document was originally released as 1-960651-xx. RAS error codes were added to this version of the manual. The part number was also changed to a standard Intermec part number.

WWAN Toolkit Programmer’s Reference Manual

iii

iv

WWAN Toolkit Programmer’s Reference Manual

Contents

Contents Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Safety Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Global Services and Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Warranty Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Web Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Send Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Telephone Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x About the Toolkit API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Power Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Turn Power On to the Built-in Radio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Turn Power Off to the Built-in Radio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 Turn Power On to the Built-in Radio Without Initialization Delay . . . . . . . . . . . . . . . . . . .13 Toolkit and Modem Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Setup WWAN Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Shutdown WWAN Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Check If the Modem Is Ready for Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Enable Modem Event Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 SIM Card Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 Check If the SIM Card Requires a PIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 Enter the PIN for a SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 Change the PIN on a SIM Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Toggle the PIN Code Entry Requirement on a SIM Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Enter the PUK for a SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 Network Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Get Network Operator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Get Network Operator ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Get Signal Strength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24 Get GPRS/1xRTT Attach Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Attach to a GPRS Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Network Selection Functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Automatic Network Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 Build a List of Available Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26 Read Details of Available Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26 Register With a Specific Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26 Build a List of Known Network Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 Read Details of Known Network Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 SMS Related Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Set the SMS Service Center Number on the SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Get the SMS Service Center Number From the SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Send an SMS Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 Get the Number of SMS Messages on the SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

WWAN Toolkit Programmer’s Reference Manual

v

Contents

Read an SMS Message From the SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 Delete an SMS Message From the SIM Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Phone Book Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Write a Phone Book Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Read a Phone Book Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Delete a Phone Book Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Telephony Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Answer an Incoming Telephone Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Hang Up a Telephone Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Make a Voice Telephone Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Send DTMF Tones During Active Voice Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Set the Duration of the DTMF Tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Telephony Audio Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Get the Current Microphone Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Set the Microphone Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Increase the Microphone Volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Decrease the Microphone Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Get the Current Speaker Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Set the Speaker Volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Increase the Speaker Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Decrease the Speaker Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Data Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 Create a RAS Entry on Pocket PC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 Delete a RAS Entry From the Pocket PC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Add a RAS Entry to the PocketPC Connection Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Remove a RAS Entry From the PocketPC Connection Manager . . . . . . . . . . . . . . . . . . . . . .39 Get Destination Information From PocketPC Connection Manager . . . . . . . . . . . . . . . . . .39 Set the Default Dial RAS Entry for PocketPC Connection Manager. . . . . . . . . . . . . . . . . . .39 Set Up a GPRS Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Get the GPRS PDP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Make a WWAN Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Make a WWAN Connection With Variable Ping Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Terminate a GPRS, 1xRTT, or Dialup Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Use RAS to Make a WWAN Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Use RAS to Make a WWAN Connection With Variable Ping Size . . . . . . . . . . . . . . . . . . . . .43 Terminate a RAS Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 Check Current WWAN Network Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 Create a New Location to Dial From . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 Delete an Existing Dialing Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 Set the Current Dialing Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 Get Connection Manager Settings for Device Network Card . . . . . . . . . . . . . . . . . . . . . . . . .46 Set Connection Manager Settings for Device Network Card. . . . . . . . . . . . . . . . . . . . . . . . . .47 Get Connection Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Error Handling Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Clear WWAN Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Get Last WWAN Error Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48 Get Last WWAN Error String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

vi

WWAN Toolkit Programmer’s Reference Manual

Contents

Radio Information Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Get the Subscriber Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Get Radio Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Get Radio Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 Obtain the Serial Number of the Radio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 Get the Manufacturer Identifier From the Radio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 Get the Model Identifier for the Radio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Determine the Firmware Version on the Radio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Get the Phone Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Determine the Radio Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 Carrier Selection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 Get the Current Carrier Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 Set the Current Carrier Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 Get the Supported Carriers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 Get the Next Supported Carrier From the Carrier List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 Get WWAN Toolkit Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

WWAN Toolkit Programmer’s Reference Manual

vii

viii

WWAN Toolkit Programmer’s Reference Manual

Before You Begin

Before You Begin This section provides you with safety information, technical support information, and sources for additional product information.

Safety Information This section explains how to identify and understand notes that are in this document. Note: Notes either provide extra information about a topic or contain special instructions for handling a particular condition or set of circumstances.

Global Services and Support Warranty Information To understand the warranty for your Intermec product, visit the Intermec website at www.intermec.com and click Support > Returns and Repairs > Warranty.

Web Support Visit the Intermec website at www.intermec.com to download our current manuals (in PDF). To order printed versions of the Intermec manuals, contact your local Intermec representative or distributor. Visit the Intermec technical knowledge base (Knowledge Central) at intermec.custhelp.com to review technical information or to request technical support for your Intermec product.

Send Feedback Your feedback is crucial to the continual improvement of our documentation. To provide feedback about this manual, please contact the Intermec Technical Communications department directly at [email protected].

Telephone Support In the U.S.A. and Canada, call 1-800-755-5505. Outside the U.S.A. and Canada, contact your local Intermec representative. To search for your local representative, from the Intermec website, click About Us > Contact Us.

Service Location Support For the most current listing of service locations, go to www.intermec.com and click Support > Returns and Repairs > Repair Locations.

WWAN Toolkit Programmer’s Reference Manual

ix

Before You Begin

For technical support in South Korea, use the after service locations listed below: AWOO Systems 102-1304 SK Ventium 522 Dangjung-dong Gunpo-si, Gyeonggi-do Korea, South 435-776 Contact: Mr. Sinbum Kang Telephone: +82-31-436-1191 Email: [email protected] IN Information System PTD LTD 6th Floor Daegu Venture Center Bldg 95 Shinchun 3 Dong Donggu, Daegu City, Korea Email: [email protected] or [email protected]

Who Should Read This Manual This document is written for the person who is responsible creating applications with the Intermec WWAN Toolkit, and provides you with information about the various functions of the WWAN Toolkit. Before you work with the WWAN Toolkit, you should be familiar with your network and general networking terms, such as IP address.

Related Documents This is a list of related Intermec documents. •

WWAN Toolkit User’s Guide

• • • • •

CN3 Mobile Computer for Windows Mobile 5.0 User’s Manual CN3 Mobile Computer for Windows Mobile 6.1 User’s Manual CN4 Mobile Computer User’s Manual CN50 Mobile Computer for Windows Mobile 6.1 User’s Manual CN50 Mobile Computer for Windows Embedded Handheld Mobile 6.5 User’s Manual

• CS40 Mobile Computer User’s Manual • 70 Series Mobile Computer User’s Manual The Intermec website at www.intermec.com contains our documents (as PDF files) that you can download for free. To download documents 1 Visit the Intermec website at www.intermec.com. 2 Click the Products tab. 3 Using the Products menu, navigate to your product page. For example, to find the CN4 computer product page, click Computers > Handheld Computers > CN4. 4 Click the Manuals tab.

x

WWAN Toolkit Programmer’s Reference Manual

Before You Begin

If your product does not have its own product page, click Support > Manuals. Use the Product Category, the Product Family, and Product to help find your documentation.

WWAN Toolkit Programmer’s Reference Manual

xi

Before You Begin

xii

WWAN Toolkit Programmer’s Reference Manual

About the Toolkit API The following sections describe all of the functions in the WWAN Toolkit’s API. The functions are grouped by their relation to one another. For additional development guidelines, see the WWAN Toolkit User’s Guide. Before using the functions in the API, note that: •

All LPTSTR definitions must be set with a length of 256 characters.

•

All methods are synchronous, which means that they do not return until the operation is completed unless otherwise stated.

For additional development guidelines, please refer to the WWAN Toolkit User’s Guide.

Power Management Functions If the WWAN Toolkit is required for only powering the integrated radio, the functions described in this section are all you need.

Turn Power On to the Built-in Radio Description: Method: Return Value:

This is the recommended means of powering the modem. This function turns on the wireless WAN radio. BOOL WWANRadioPowerOn() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Turn Power Off to the Built-in Radio Description: Method: Return Value:

This function turns off the wireless WAN radio. BOOL WWANRadioPowerOff() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Turn Power On to the Built-in Radio Without Initialization Delay Description:

This method of powering the modem turns the power on to the wireless WAN radio. Note: This function is used with caution, as it does not have the delays that are built into WWANRadioPowerOn()to ensure that the modem is initialized before setting up the toolkit. When using this function it is important to make sure that the application initialization takes a minimum of 15 seconds as this ensures that the modem is ready to accept the commands used in the toolkit setup.

Method: Return Value:

BOOL WWANRadioPowerOnNoDelay() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

WWAN Toolkit Programmer’s Reference Manual

13

Toolkit and Modem Setup This section describes the toolkit and modem setup functions.

Setup WWAN Toolkit Description:

Method: Return Value:

This function initializes the communications ports and other internal toolkit classes and data structures. It must be called before using any toolkit functions other than WWANRadioPowerOn(), WWANRadioPowerOff(), or WWANRadioPowerOnNoDelay(). BOOL SetupWWANToolKit() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Shutdown WWAN Toolkit Description:

This function closes the communications port and frees memory allocated by the toolkit. Note: This function does not power off the modem.

Method: Return Value:

BOOL ShutDownToolkit() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Check If the Modem Is Ready for Use Description: Method: Return Value:

This function checks that the modem is responding. If the modem is not responding this function could take up to sixty seconds to execute. BOOL IsModemReady() The function returns a Boolean TRUE if the modem is responding or a Boolean FALSE if the modem is not responding. The function returns TRUE even if the SIM card requires a PIN code to unlock it.

Enable Modem Event Reporting Description: Method: Return Value:

This function sets up the callback mechanisms to report the various modem events. BOOL SetModemEventReporting (HWND pParent, int CallbackNumber) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions

14

Parameter

Description

pParent

Handle of window to receive event notifications, set = NULL to disable event reporting.

CallbackNumber

Unsigned integer containing the Windows message number, set = 0 to disable event reporting. Valid values are “WM_USER“ through “0x7FFF“.

WWAN Toolkit Programmer’s Reference Manual

Function Events:

Events are reported to the window with a handle specified by the parameter pParent using the windows message specified by the CallbackNumber parameter. The following tables show the events that are reported. Note that the wParam parameter values in the table are defined in the WWAN Toolkit header file. Modem Events That Are Reported wParam

Description

lParam

Modem Support

01

Signal Strength*

0-5

Supported on all

03

SMS Envelope indicator

0/1

04

Call in Progress

0/1

05

Roaming Indicator

0/1

Not CDMA

07

SIM SMS Full

0/1

Not CDMA

10

New SMS received

SMS location

Not CDMA

11

Network Availability

0/1

Supported on all

20

Incoming call

0 = Unknown 1 = Voice 2 = Data 3 = Fax

Supported on all

21

Caller ID

Pointer to data. Pointer is of type LPCTSTR (TCHAR).

40

RAS Callbacks

See the RAS Callback Events Supported on all That Are Reported table below.

41

RAS Error Callbacks

See the RAS Callback Events Supported on all That Are Reported table below.

100

Connection Manager

See the RAS Callback Events Supported on all That Are Reported table below.

RAS Callback Events That Are Reported RAS Callbacks – lParam Values

Description

RASCS_AuthNotify

An authentication event has occurred. If dwError is zero, this event is immediately followed by one of the more specific authentication states following. If dwError is nonzero, authentication has failed, and the error value indicates why.

RASCS_AuthRetry

The client has requested another validation attempt with a new user name/password/domain.

RASCS_AuthCallback

The remote access server has requested a callback number. This occurs only if the user has “Set By Caller” callback privilege on the server.

RASCS_AuthChangePassword

The client has requested to change the password on the account.

RASCS_AuthProject

The projection phase is starting.

RASCS_AuthLinkSpeed

The link-speed calculation phase is starting.

RASCS_AuthAck

An authentication request is being acknowledged.

RASCS_ReAuthenticate

Reauthentication (after callback) is starting.

WWAN Toolkit Programmer’s Reference Manual

15

RAS Callback Events That Are Reported (continued) RAS Callbacks – lParam Values

Description

RASCS_Authenticated

The client has successfully completed authentication.

RASCS_PrepareForCallback

The line is about to disconnect in preparation for callback.

RASCS_WaitForModemReset

The client is delaying in order to give the modem time to reset itself in preparation for callback.

RASCS_WaitForCallback

The client is waiting for an incoming call from the remote access server.

RASCS_Projected

This state occurs after the RASCS_AuthProject state. It indicates that projection result data is available.

RASCS_Interactive

This state corresponds to the terminal state.

RASCS_RetryAuthentication

This state corresponds to the retry authentication state.

RASCS_Connected

Successful connection.

RASCS_Disconnected

Disconnection or failed connection.

Connection Manager Callback Events That Are Reported Connection Manager Callbacks - lParams Values

Description

CONNMGR_STATUS_UNKNOWN

The status is unknown.

WWANTK_STOPPED_CONNECTION

This occurs when DoDialUpHangup is called.

CONNMGR_STATUS_CONNECTED

The connection is up.

CONNMGR_STATUS_DISCONNECTED

The connection has been disconnected by connection manager.

CONNMGR_STATUS_WAITINGFORPATH

A path to the destination exists but is not presently available (for example, the device is out of radio range or is not plugged into its cradle).

CONNMGR_STATUS_WAITINGFORRESOURCE

Another client is using resources that this connection requires.

CONNMGR_STATUS_WAITINGFORPHONE

A voice call is in progress and is using resources that this connection requires.

CONNMGR_STATUS_WAITINGFORNETWORK

The device is waiting for a task with a higher priority to connect to the network before connecting to the same network. This status value is only returned to clients that specified a priority of CONNMGR_PRIORITY_LOWBKGND when requesting a connection.

CONNMGR_STATUS_NOPATHTODESTINATION

No path to the destination could be found.

CONNMGR_STATUS_CONNECTIONFAILED

The connection failed and cannot be reestablished. Also occurs when a ping failure is detected – refer to DoDialUpConnect function.

CONNMGR_STATUS_CONNECTIONDISABLED

The connection can be made, but the connection itself is disabled. This value is only returned to clients that set the bDisabled value in the CONNMGR_CONNECTIONINFO structure.

CONNMGR_STATUS_WAITINGCONNECTION

The device is attempting to connect.

CONNMGR_STATUS_WAITINGCONNECTIONABORT The device is aborting the connection attempt. CONNMGR_STATUS_WAITINGDISCONNECTION

The connection is being brought down.

For more information, see the WWAN Toolkit User’s Guide.

16

WWAN Toolkit Programmer’s Reference Manual

RAS Error Callback Events That Are Reported RAS Error Callbacks - Iparam Values

Description

PENDING

An operation is pending.

ERROR_INVALID_PORT_HANDLE

An invalid port handle was detected.

ERROR_PORT_ALREADY_OPEN

The specified port is already open.

ERROR_BUFFER_TOO_SMALL

The caller's buffer is too small.

ERROR_WRONG_INFO_SPECIFIED

Incorrect information was specified.

ERROR_CANNOT_SET_PORT_INFO

The port information cannot be set.

ERROR_PORT_NOT_CONNECTED

The specified port is not connected.

ERROR_EVENT_INVALID

An invalid event was detected.

ERROR_DEVICE_DOES_NOT_EXIST

A device was specified that does not exist.

ERROR_DEVICETYPE_DOES_NOT_EXIST

A device type was specified that does not exist.

ERROR_BUFFER_INVALID

An invalid buffer was specified.

ERROR_ROUTE_NOT_AVAILABLE

A route was specified that is not available.

ERROR_ROUTE_NOT_ALLOCATED

A route was specified that is not allocated.

ERROR_INVALID_COMPRESSION_SPECIFIED

An invalid compression was specified.

ERROR_OUT_OF_BUFFERS

There were insufficient buffers available.

ERROR_PORT_NOT_FOUND

The specified port was not found.

ERROR_ASYNC_REQUEST_PENDING

An asynchronous request is pending.

ERROR_ALREADY_DISCONNECTING

The modem (or other connecting device) is already disconnecting.

ERROR_PORT_NOT_OPEN

The specified port is not open.

ERROR_PORT_DISCONNECTED

The specified port is not connected.

ERROR_NO_ENDPOINTS

No endpoints could be determined.

ERROR_CANNOT_OPEN_PHONEBOOK

The system could not open the phone book file.

ERROR_CANNOT_LOAD_PHONEBOOK

The system could not load the phone book file.

ERROR_CANNOT_FIND_PHONEBOOK_ENTRY

The system could not find the phone book entry for this connection.

ERROR_CANNOT_WRITE_PHONEBOOK

The system could not update the phone book file.

ERROR_CORRUPT_PHONEBOOK

The system found invalid information in the phone book file.

ERROR_CANNOT_LOAD_STRING

A string could not be loaded.

ERROR_KEY_NOT_FOUND

A key could not be found.

ERROR_DISCONNECTION

The connection was closed.

ERROR_REMOTE_DISCONNECTION

The connection was closed by the remote computer.

ERROR_HARDWARE_FAILURE

The modem (or other connecting device) was disconnected due to hardware failure.

ERROR_USER_DISCONNECTION

The user disconnected the modem (or other connecting device).

ERROR_INVALID_SIZE

An incorrect structure size was detected.

ERROR_PORT_NOT_AVAILABLE

The modem (or other connecting device) is already in use or is not configured properly.

ERROR_CANNOT_PROJECT_CLIENT

Your computer could not be registered on the remote network.

ERROR_UNKNOWN

There was an unknown error.

ERROR_WRONG_DEVICE_ATTACHED

The device attached to the port is not the one expected.

WWAN Toolkit Programmer’s Reference Manual

17

RAS Error Callback Events That Are Reported (continued) RAS Error Callbacks - Iparam Values

Description

ERROR_BAD_STRING

A string was detected that could not be converted.

ERROR_REQUEST_TIMEOUT

The request has timed out.

ERROR_CANNOT_GET_LANA

No asynchronous net is available.

ERROR_NETBIOS_ERROR

An error has occurred involving NetBIOS.

ERROR_SERVER_OUT_OF_RESOURCES

The server cannot allocate NetBIOS resources needed to support the client.

ERROR_NAME_EXISTS_ON_NET

One of your computer's NetBIOS names is already registered on the remote network.

ERROR_SERVER_GENERAL_NET_FAILURE

A network adapter at the server failed.

WARNING_MSG_ALIAS_NOT_ADDED

You will not receive network message popups.

ERROR_AUTH_INTERNAL

There was an internal authentication error.

ERROR_RESTRICTED_LOGON_HOURS

The account is not permitted to log on at this time of day.

ERROR_ACCT_DISABLED

The account is disabled.

ERROR_PASSWD_EXPIRED

The password for this account has expired.

ERROR_NO_DIALIN_PERMISSION

The account does not have permission to dial in.

ERROR_SERVER_NOT_RESPONDING

The remote access server is not responding.

ERROR_FROM_DEVICE

The modem (or other connecting device) has reported an error.

ERROR_UNRECOGNIZED_RESPONSE

There was an unrecognized response from the modem (or other connecting device).

ERROR_MACRO_NOT_FOUND

A macro required by the modem (or other connecting device) was not found in the device.INF file.

ERROR_MACRO_NOT_DEFINED

A command or response in the device.INF file section refers to an undefined macro.

ERROR_MESSAGE_MACRO_NOT_FOUND

The macro was not found in the device.INF file section.

ERROR_DEFAULTOFF_MACRO_NOT_FOUND

The macro in the device.INF file section contains an undefined macro.

ERROR_FILE_COULD_NOT_BE_OPENED

The device.INF file could not be opened.

ERROR_DEVICENAME_TOO_LONG

The device name in the device.INF or media.INI file is too long.

ERROR_DEVICENAME_NOT_FOUND

The media.INI file refers to an unknown device name.

ERROR_NO_RESPONSES

The device.INF file contains no responses for the command.

ERROR_NO_COMMAND_FOUND

The device.INF file is missing a command.

ERROR_WRONG_KEY_SPECIFIED

There was an attempt to set a macro not listed in device.INF file section.

ERROR_UNKNOWN_DEVICE_TYPE

The media.INI file refers to an unknown device type.

ERROR_ALLOCATING_MEMORY

The system has run out of memory.

ERROR_PORT_NOT_CONFIGURED

The modem (or other connecting device) is not properly configured.

ERROR_DEVICE_NOT_READY

The modem (or other connecting device) is not functioning.

ERROR_READING_INI_FILE

The system was unable to read the media.INI file.

ERROR_NO_CONNECTION

The connection was terminated.

ERROR_BAD_USAGE_IN_INI_FILE

The usage parameter in the media.INI file is invalid.

18

WWAN Toolkit Programmer’s Reference Manual

RAS Error Callback Events That Are Reported (continued) RAS Error Callbacks - Iparam Values

Description

ERROR_READING_SECTIONNAME

The system was unable to read the section name from the media.INI file.

ERROR_READING_DEVICETYPE

The system was unable to read the device type from the media .INI file.

ERROR_READING_DEVICENAME

The system was unable to read the device name from the media .INI file.

ERROR_READING_USAGE

The system was unable to read the usage from the media.INI file.

ERROR_READING_MAXCONNECTBPS

The system was unable to read the maximum connection BPS rate from the media .INI file.

ERROR_READING_MAXCARRIERBPS

The system was unable to read the maximum carrier connection speed from the media .INI file.

ERROR_LINE_BUSY

The phone line is busy.

ERROR_VOICE_ANSWER

A person answered instead of a modem (or other connecting device).

ERROR_NO_ANSWER

There was no answer.

ERROR_NO_CARRIER

The system could not detect the carrier.

ERROR_NO_DIALTONE

There was no dial tone.

ERROR_IN_COMMAND

The modem (or other connecting device) reported a general error.

ERROR_WRITING_SECTIONNAME

There was an error in writing the section name.

ERROR_WRITING_DEVICETYPE

There was an error in writing the device type.

ERROR_WRITING_DEVICENAME

There was an error in writing the device name.

ERROR_WRITING_MAXCONNECTBPS

There was an error in writing the maximum connection speed.

ERROR_WRITING_MAXCARRIERBPS

There was an error in writing the maximum carrier speed.

ERROR_WRITING_USAGE

There was an error in writing the usage.

ERROR_WRITING_DEFAULTOFF

There was an error in writing the default-off.

ERROR_READING_DEFAULTOFF

There was an error in reading the default-off.

ERROR_EMPTY_INI_FILE

The media .INI file is empty.

ERROR_AUTHENTICATION_FAILURE

Access was denied because the username and/or password was invalid on the domain.

ERROR_PORT_OR_DEVICE

There was a hardware failure in the modem (or other connecting device).

ERROR_NOT_BINAERROR_NOT_BINARY_MACRORY The macro is not a binary macro. _MACRO ERROR_DCB_NOT_FOUND

DCB not found.

ERROR_STATE_MACHINES_NOT_STARTED

The state machines are not started.

ERROR_STATE_MACHINES_ALREADY_STARTED

The state machines are already started.

ERROR_PARTIAL_RESPONSE_LOOPING

The response looping did not complete.

ERROR_UNKNOWN_RESPONSE_KEY

A response keyname in the device.INF file is not in the expected format.

ERROR_RECV_BUF_FULL

The modem (or other connecting device) response caused a buffer overflow.

ERROR_CMD_TOO_LONG

The expanded command in the device.INF file is too long.

WWAN Toolkit Programmer’s Reference Manual

19

RAS Error Callback Events That Are Reported (continued) RAS Error Callbacks - Iparam Values

Description

ERROR_UNSUPPORTED_BPS

The modem moved to a connection speed not supported by the COM driver.

ERROR_UNEXPECTED_RESPONSE

Device response received when none expected.

ERROR_INTERACTIVE_MODE

The connection needs information from you, but the application does not allow user interaction.

ERROR_BAD_CALLBACK_NUMBER

The callback number is invalid.

ERROR_INVALID_AUTH_STATE

The authorization state is invalid.

ERROR_WRITING_INITBPS

An error occurred when writing the initial connection speed.

ERROR_X25_DIAGNOSTIC

There was an error related to the X.25 protocol.

ERROR_ACCT_EXPIRED

The account has expired.

ERROR_CHANGING_PASSWORD

There was an error changing the password on the domain. The password might have been too short or might have matched a previously used password.

ERROR_OVERRUN

Serial overrun errors were detected while communicating with the modem.

ERROR_RASMAN_CANNOT_INITIALIZE

The Remote Access Service Manager could not start. Additional information is provided in the event log.

ERROR_BIPLEX_PORT_NOT_AVAILABLE

The two-way port is initializing. Wait a few seconds and redial.

ERROR_NO_ACTIVE_ISDN_LINES

No active ISDN lines are available.

ERROR_NO_ISDN_CHANNELS_AVAILABLE

No ISDN channels are available to make the call.

ERROR_TOO_MANY_LINE_ERRORS

Too many errors occurred because of poor phone line quality.

ERROR_IP_CONFIGURATION

The Remote Access Service IP configuration is unusable.

ERROR_NO_IP_ADDRESSES

No IP addresses are available in the static pool of Remote Access Service IP addresses.

ERROR_PPP_TIMEOUT

The connection timed out waiting for a valid response from the remote computer.

ERROR_PPP_REMOTE_TERMINATED

The connection was terminated by the remote computer.

ERROR_PPP_NO_PROTOCOLS_CONFIGURED

The connection attempt failed because your computer and the remote computer could not agree on PPP control protocols.

ERROR_PPP_NO_RESPONSE

The remote computer is not responding.

ERROR_PPP_INVALID_PACKET

Invalid data was received from the remote computer. This data was ignored.

ERROR_PHONE_NUMBER_TOO_LONG

The phone number, including prefix and suffix, is too long.

ERROR_IPXCP_NO_DIALOUT_CONFIGURED

The IPX protocol cannot dial out on the modem (or other connecting device) because this computer is not configured for dialing out (it is an IPX router).

ERROR_IPXCP_NO_DIALIN_CONFIGURED

The IPX protocol cannot dial in on the modem (or other connecting device) because this computer is not configured for dialing in (the IPX router is not installed).

ERROR_IPXCP_DIALOUT_ALREADY_ACTIVE

The IPX protocol cannot be used for dialing out on more than one modem (or other connecting device) at a time.

ERROR_ACCESSING_TCPCFGDLL

Cannot access TCPCFG.DLL.

ERROR_NO_IP_RAS_ADAPTER

The system cannot find an IP adapter.

ERROR_SLIP_REQUIRES_IP

SLIP cannot be used unless the IP protocol is installed.

20

WWAN Toolkit Programmer’s Reference Manual

RAS Error Callback Events That Are Reported (continued) RAS Error Callbacks - Iparam Values

Description

ERROR_PROJECTION_NOT_COMPLETE

Computer registration is not complete.

ERROR_PROTOCOL_NOT_CONFIGURED

The protocol is not configured.

ERROR_PPP_NOT_CONVERGING

Your computer and the remote computer could not agree on PPP control protocols.

ERROR_PPP_CP_REJECTED

Your computer and the remote computer could not agree on PPP control protocols.

ERROR_PPP_LCP_TERMINATED

The PPP link control protocol was terminated.

ERROR_PPP_REQUIRED_ADDRESS_REJECTED

The requested address was rejected by the server.

ERROR_PPP_NCP_TERMINATED

The remote computer terminated the control protocol.

ERROR_PPP_LOOPBACK_DETECTED

Loopback was detected.

ERROR_PPP_NO_ADDRESS_ASSIGNED

The server did not assign an address.

ERROR_CANNOT_USE_LOGON_CREDENTIALS

The authentication protocol required by the remote server cannot use the stored password. Redial, entering the password explicitly.

ERROR_TAPI_CONFIGURATION

An invalid dialing rule was detected.

ERROR_NO_LOCAL_ENCRYPTION

The local computer does not support the required data encryption type.

ERROR_NO_REMOTE_ENCRYPTION

The remote computer does not support the required data encryption type.

ERROR_REMOTE_REQUIRES_ENCRYPTION

The remote computer requires data encryption.

ERROR_IPXCP_NET_NUMBER_CONFLICT

The system cannot use the IPX network number assigned by the remote computer. Additional information is provided in the event log.

ERROR_INVALID_SMM

The Session Management Module (SMM) is invalid.

ERROR_SMM_UNINITIALIZED

The SMM is uninitialized.

ERROR_NO_MAC_FOR_PORT

No MAC for port.

ERROR_SMM_TIMEOUT

The SMM timed out.

ERROR_BAD_PHONE_NUMBER

A bad phone number was specified.

ERROR_WRONG_MODULE

The wrong SMM was specified.

ERROR_PPP_MAC

Error with Media Access Control of the Point to Point Protocol.

ERROR_PPP_LCP

Error with Link Control Protocol of the Point to Point Protocol.

ERROR_PPP_AUTH

Error with Point to Point Protocol Authorization.

ERROR_PPP_NCP

Error with Network Control Protocol of the Point to Point Protocol.

ERROR_POWER_OFF

Power off Error.

ERROR_POWER_OFF_CD

Power off Error.

ERROR_DIAL_ALREADY_IN_PROGRESS

Another thread has either already initiated an Auto dial connection or is in the process of establishing a connection.

ERROR_RASAUTO_CANNOT_INITIALIZE

The registry key is not present or no RAS entry name is specified in the registry.

ERROR_UNABLE_TO_AUTHENTICATE_SERVER

It was not possible to verify the identity of the server.

ERROR_IDLE_DISCONNECTED

The port has been disconnected due to inactivity.

WWAN Toolkit Programmer’s Reference Manual

21

SIM Card Management This section describes the SIM card management functions.

Check If the SIM Card Requires a PIN Description:

Method: Return Value:

This function checks the SIM card to see if a PIN code is required. The routine returns an integer value to correspond with the enumerated response of the modem. The responses are detailed in the function response section. Use the IsModemReady() function to see if the modem is actually ready. On CDMA networks, this function always returns a state of PIN_READY for cross device support. PIN_CODES CheckSimPin() where function values returned are: Function Values and Their Description Function Value

Description

PIN_CODES

This defines the status of the SIM in the modem.

PIN_ERROR

When any error condition occurs, for example there is not a SIM card inserted.

PIN_READY

SIM card is unlocked and ready to be used.

PIN_SIM_PIN

SIM card is locked and requires a PIN code to be entered.

PIN_SIM_PUK

SIM card is locked and requires a PUK code to be entered.

PIN_SIM_PUK2

IM card is locked and requires a PUK2 code to be entered.

Enter the PIN for a SIM Card Description:

This function sends the PIN Number to the modem. Use this function in conjunction with the CheckSimPin()function detailed above. Before you call this function you should call the CheckSimPin() function. After calling this function you should call the CheckSimPin() function again to ensure the status of the SIM card. Note: This function is not supported on CDMA networks.

Method: Return Value:

BOOL EnterSimPin( LPCTSTR PinNumber ) The fuction returns a Boolean TRUE when the PIN Number is sent to the modem successfully. This does not guarantee that the PIN number entered was correct. A Boolean FALSE is returned if the PIN was not sent to the modem successfully. Parameter Descriptions

22

Parameter

Description

PinNumber

String containing the four digit PIN code.

WWAN Toolkit Programmer’s Reference Manual

Change the PIN on a SIM Card Description:

This function changes the PIN code for a SIM card. Call this function with both the new PIN code and the previous PIN code for a successful change. Note: This method requires that the “Lock” function is enabled (Call TurnSimPinOnOff() with parameter On = TRUE). Note: This function is not supported on CDMA networks.

Method: Return Value:

BOOL ChangeSimPin( LPCTSTR OldPin, LPCTSTR NewPin ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

OldPin

String containing the current four digit PIN code such as 1234.

NewPin

String containing the new four digit PIN code such as 4321.

Toggle the PIN Code Entry Requirement on a SIM Card Description:

This function changes the requirement for PIN code entry for a SIM card. For security, the function requires the entry of the PIN code as well as the desired state of the PIN code requirement. Note: This function is not supported on CDMA networks.

Method: Return Value:

BOOL TurnSimPinOnOff( LPCTSTR OldPin, BOOL On ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

OldPin

String containing the current four digit PIN code such as 1234.

On

A Boolean TRUE means that the PIN code is switched on, while a Boolean FALSE means that the PIN code is switched off.

Enter the PUK for a SIM Card Description:

The PUK number is the ‘Phone Unlock Key’ that is required when the PIN number has been entered incorrectly 3 times. This function sends the PUK Number to the modem. The function should only be used after the CheckSimPin() function returns a PIN_SIM_PUK value. Before you call this function, call the CheckSimPin() function. After calling this function, call the CheckSimPin() function again to ensure the status of the SIM card. Note: This function is not supported on CDMA networks.

WWAN Toolkit Programmer’s Reference Manual

23

Method: Return Value:

BOOL EnterPukNumber( LPCTSTR PUK, LPCTSTR NewPin ) The returned value is a Boolean TRUE when the PUK Number is sent to the modem successfully. A Boolean FALSE is returned if the PUK was not sent to the modem successfully. Parameter Descriptions Parameter

Description

PUK

String containing PUK code.

NewPin

String containing the new for digit PIN code such as 1234.

Network Information Functions This section describes the network information functions.

Get Network Operator Description: Method: Return Value:

This function returns the name of the current network operator that you are registered with. LPCTSTR GetOperator() The function returns the name of the current network operator or “Not Registered” if the information could not be obtained.

Get Network Operator ID Description: Method: Return Value:

This function returns the identity code of the GSM/GPRS network operator that you are currently registered with. LPCTSTR GetOperatorID() The function returns the identity code of the operator or “Not Registered” if the information could not be obtained.

Get Signal Strength Description: Method: Return Value:

This function asks the modem to return the current signal strength. This value is then converted to a number of bars as displayed on a mobile phone. BOOL SignalStrength( int *Strength ) The function returns a Boolean TRUE, and the parameter Strength contains a value, if the function is successful. If the function fails then the function returns a Boolean FALSE with the parameter Strength equal to 0. Parameter Descriptions

24

Parameter

Description

Strength

Integer containing the signal strength in a range corresponding to the bars displayed by a mobile phone: 0 to 5 for all devices.

WWAN Toolkit Programmer’s Reference Manual

Get GPRS/1xRTT Attach Status Description: Method: Return Value:

This function returns the current GPRS status. BOOL GetGPRSAttach() The function returns TRUE if your GSM wireless radio is attached to a GPRS network. If the GSM wireless radio is not attached to a GPRS network then the function returns FALSE. If you are using a CDMA device then the CDMA equivalent network call is used to determine if a 1xRTT network is present.

Attach to a GPRS Network Description:

This function attachs to and detachs from a GPRS network. Use the GetGPRSAttach function to check the status both before and after calling this function. Note: This method can take up to 60 seconds to complete.

Method: Return Value:

BOOL SetGPRSAttach( BOOL State ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. If you are using a CDMA device this always returns FALSE. Parameter Descriptions Parameter

Description

State

Set TRUE to attach to the GPRS network. Set FALSE to detach from the GPRS network.

Network Selection Functionality This section describes the network selection functions. Note: The functions below are not supported on CDMA devices.

Automatic Network Registration Description:

Method: Return Value:

It is possible to let the GPRS radio and SIM card select the best network for your device to use. In order to do this automatic network registration use this function. No other methods are required to achieve this. BOOL AutomaticNetworkRegister() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

WWAN Toolkit Programmer’s Reference Manual

25

Build a List of Available Networks Description:

Method: Return Value:

The toolkit uses this function to build an internal list of all of the network operators the device can see. This function is called before calling the GetNextAvailNetworkOperator() function. The GetNextAvailNetworkOperator() function reads the details of the list. BOOL GetAvailNetworkOperators() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Read Details of Available Network Description:

Method: Return Value:

This function reads details of the next entry in the toolkit’s internal list of available networks. The GetAvailNetworkOperators() function should be used to build the internal list just before this function is called for the first time. BOOL GetNextAvailNetworkOperator( int *ConnectionStatus, LPTSTR NetworkName, LPTSTR NetworkId ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. To get the entire list of available network operators, repeatedly call this function until it returns with a FALSE. Parameter Descriptions Parameter

Description

ConnectionStatus

A number indicating if a connection to the network is possible. This can be one of the following: • 0: Unknown. • 1: Operator available. • 2: Current operator (registered) • 3: Forbidden operator, normally competing operator within the same territory as the home network operator SIM provider.

NetworkName

String containing the name of the available network, such as Vodafone SE or Q2 UK.

NetworkID

String containing the ID of the available network, such as 240 08 or 234 10.

Register With a Specific Network Description:

Method:

26

If you wish to register with an available network, use this function. It is important that you check that the network you wish to register with is currently available to your device. Use the GetAvailNetworkOperators() function and the GetNextAvailNetworkOperator() function to determine the available networks. BOOL RegisterWithOperator( LPCTSTR OperatorId )

WWAN Toolkit Programmer’s Reference Manual

Return Value:

The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

OperatorID

String containing the ID of the available network, such as 240 08 or 234 10.

Build a List of Known Network Operators Description:

Method: Return Value:

The toolkit uses this function to build an internal list of all of the network operators the device knows about. This function should be called before calling the GetNextKnownNetworkOperator()function. The GetNextKnownNetworkOperator() function reads the details of the list. BOOL GetKnownNetworkOperators() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Read Details of Known Network Operators Description:

Method: Return Value:

This function reads the details of the next entry in the toolkit’s internal list of known networks. The GetKnownNetworkOperators() function is used to build the internal list just before this function is called for the first time. This is not supported on CDMA devices. BOOL GetNextKnownNetworkOperator( LPTSTR NetworkName, LPTSTR NetworkId ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. To get the entire list of available network operators, repeatedly call this function until it returns with a FALSE. Parameter Descriptions Parameter

Description

NetworkName

String containing the name of the available network, such as Vodafone SE or O2 UK.

NetworkID

String containing the ID of the available network, such as 240 08 or 234 10.

WWAN Toolkit Programmer’s Reference Manual

27

SMS Related Features This section describes all SMS related functions.

Set the SMS Service Center Number on the SIM Card Description:

This function sets the SMS service center number, which is commonly predefined on the SIM card. Note: The functions below are not supported on CDMA networks.

Method: Return Value:

BOOL SetSMSCentre( LPCTSTR SMSCentreNumber ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

SMSCentreNumber

String containing the telephone number of the SMS Center. It must be in the full international number format, such as +441189876543.

Get the SMS Service Center Number From the SIM Card Description:

This function gets the SMS service center number from the SIM card. Note: The functions below are not supported on CDMA networks.

Method: Return Value:

LPCTSTR GetSMSCentre() The function returns a string value of the SMS service center number set on the SIM card.

Send an SMS Message Description: Method: Return Value:

This function sends an SMS message to another mobile device. BOOL SendSMS(LPCTSTR SmsCentre, LPCTSTR PhoneNumber, LPCTSTR SmsData ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions

28

Parameter

Description

SMSCentre

String containing the telephone number of the SMS Center. It must be in the full international number format, such as +441189876543.

PhoneNumber

String containing the number of the GSM mobile device to receive the message. The number can be a normal phone number or an international format number.

WWAN Toolkit Programmer’s Reference Manual

Parameter Descriptions (continued) Parameter

Description

SmsData

String containing the text of the message to be sent. A maximum of 160 characters are allowed.

Get the Number of SMS Messages on the SIM Card Description: Method: Return Value:

This function returns the number of SMS messages that are currently stored by the toolkit. BOOL NumberOfSms( int *Total ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Total

The number of currently saved messages.

Read an SMS Message From the SIM Card Description:

Method: Return Value:

This function retrieves the SMS text message at the specified location. To determine the message location numbers, applications should use the ‘New SMS Received’ event notification mechanism. This function does not delete the message at the specified location. BOOL ReadSMS( int Location, LPTSTR PhoneNumber, LPTSTR TimeStamp, LPTSTR SmsData ) The function returns a Boolean TRUE if successful or a Boolean FALSE if no SMS messages are available to be read. Parameter Descriptions Parameter

Description

Location

Integer specifying the location index of the desired message. The range is 1 to an upper limit, which varies by device.

PhoneNumber

String containing the number of the device that sent the message. The number can be a normal phone number or an international format number.

TimeStamp

Date and time the message was sent in the format year/month/ day, hour:minute:second, millisecond, such as 02/07/19,08:49:10,04.

SmsData

String containing the text of the message. A maximum of 160 characters are allowed.

WWAN Toolkit Programmer’s Reference Manual

29

Delete an SMS Message From the SIM Card Description: Method: Return Value:

This function deletes the SMS text message at the specified location. BOOL DeleteSms( int Location ) Upon a successful completion of the routine a Boolean TRUE is returned, otherwise a Boolean FALSE is returned. Parameter Descriptions Parameter

Description

Location

Integer specifying the location index of the message to delete. The range is 1 to an upper limit, which varies by device.

Phone Book Features This section describes phone book feature functions.

Write a Phone Book Entry Description:

This function adds an entry to the phone book stored on the device. On devices with a SIM card, such as those operating on GSM networks, this information is stored on the SIM card. On devices without a SIM card, such as those operating on CDMA networks, this information is stored in a special file maintained by the toolkit. This function call returns an error when no more slots are available in the phone book. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL WritePhoneBookEntry( LPCTSTR PhoneNumber, LPCTSTR Name ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions

30

Parameter

Description

PhoneNumber

String containing the telephone number to store. It is good practice to prefix it with a plus sign and the international country code, such as +44118987654.

Name

String containing the name associated with the telephone number being stored.

WWAN Toolkit Programmer’s Reference Manual

Read a Phone Book Entry Description:

This function retrieves a phone book entry from the device. On devices with a SIM card, such as those operating on GSM networks, this information is retrieved from the SIM card. On devices without a SIM card, such those operating on CDMA networks, this information is retrieved from a special file maintained by the toolkit. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL ReadPhoneBookEntry( int Location, LPTSTR PhoneNumber, LPTSTR Name ) The function returns a Boolean TRUE if successful or a Boolean FALSE if there is no entry or the location is out of range. Parameter Descriptions Parameter

Description

Location

Integer specifying the location of the phone book entry to retrieve. The range is 1 to an upper limit, which varies by device.

PhoneNumber

String containing the telephone number to call. It is good practice to prefix it with a plus sign and the international country code, such as +441189876543.

Name

String containing the name associated with the telephone number to call.

Delete a Phone Book Entry Description:

This function removes a phone book entry from the device. On devices with a SIM card, such as those operating on GSM networks, the entry is deleted from the phone book stored on the SIM card. On devices without a SIM card, such as those operating on CDMA networks, the entry is deleted from the special phone book file created by the toolkit. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL DeletePhoneBookEntry( int Location ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Location

Integer specifying the location of the phone book entry to delete. The range is 1 to an upper limit, which varies by device.

WWAN Toolkit Programmer’s Reference Manual

31

Telephony Functions This section describes the telephony functions.

Answer an Incoming Telephone Call Description:

This function answers an incoming phone call. The event generated by the incoming call shows the type of call i.e. voice, data or fax. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL AnswerPhoneCall() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Hang Up a Telephone Call Description:

This function ends a phone call. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL HangUpPhoneCall( BOOL Data ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Data

Set TRUE if ending a data or fax call, set FALSE if ending a voice call. (A Boolean parameter is required to ensure that the correct mode is used to communicate with the modem.)

Make a Voice Telephone Call Description:

This function initiates a voice telephone call. The parameter PhoneNumber is required. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL MakeVoicePhoneCall( LPCTSTR PhoneNumber ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions

32

Parameter

Description

PhoneNumber

String containing the telephone number to call. It is good practice to prefix it with a plus sign and the international country code, such as +441189876543.

WWAN Toolkit Programmer’s Reference Manual

Send DTMF Tones During Active Voice Calls Description:

This function sends DTMF tones to recipient of voice call (tones which correspond to specific button presses). Only call this method when in an active voice call. If this method is sent during a data session, whether circuit switched or packet switched, errors may occur in the data transmission. To setup DTMF in an application, you must catch the button events while in a voice call and translate that to the appropriate DTMF tone. The duration of the tone can be configured using the DTMFToneDuration method. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL DTMFToneSend( DTMF_TONES ToneToSend ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ToneToSend

Data of type DTMF_TONES, which should only be one of the following: DTMF_0 through DTMF_9 These correspond to the numbers 0 through 9 on a regular telephone keypad. DTMF_STAR This corresponds to the star key (*) on a regular telephone keypad. DTMF_HASH, DTMF_POUND These correspond to the hash (or pound) key (#) on a regular telephone keypad. DTMF_A through DTMF_D These correspond to the extended DTMF tones for the letters A through D.

Set the Duration of the DTMF Tones Description:

This function sets the duration of all subsequent DTMF tones sent to the recipient of a voice call. It is only required to call this method once, unless it is required to change the duration. The DTMF tone is sent using the DTMFToneSend method. Note: This function is not supported on devices with a data-only radio.

Note: This function is not supported on CDMA networks.

Method:

BOOL DTMFToneDuration( int ToneDuration )

WWAN Toolkit Programmer’s Reference Manual

33

Return Value:

The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ToneDuration

Integer value of duration of tone in milliseconds. Must be in the range of 100 to 25000.

Telephony Audio Functions This section describes the telephony audio functions.

Get the Current Microphone Volume Description:

This function retrieves the current audio gain level (volume) of the microphone. Note: This function is not supported on devices with a data-only radio.

Note: This function is not supported on the CN4, CN50, or CS40.

Method: Return Value:

BOOL GetMicVol( int *Level ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Level

Returns an integer between 0 (quiet) and 19 (loud).

Set the Microphone Volume Description:

This function sets the current audio gain level (volume) of the microphone. Note: This function is not supported on devices with a data-only radio.

Note: This function is not supported on the CN4, CN50, or CS40.

Method:

BOOL SetMicVol( int Level ) Parameter Descriptions

34

Parameter

Description

Level

Returns an integer between 0 (quiet) and 19 (loud).

WWAN Toolkit Programmer’s Reference Manual

Increase the Microphone Volume Description:

This function increases the audio gain level (volume) of the microphone by 1. Note: This function is not supported on devices with a data-only radio.

Note: This function is not supported on the CN4, CN50, or CS40.

Method: Return Value:

BOOL IncreaseMicVol() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Decrease the Microphone Volume Description:

This function decreases the audio gain level (volume) of the microphone by 1. Note: This function is not supported on devices with a data-only radio.

Note: This function is not supported on the CN4, CN50, or CS40.

Method: Return Value:

BOOL decreaseMicVol() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Get the Current Speaker Volume Description:

This function retrieves the current audio gain level (volume) of the speaker. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL GetSpeakerVol( int *Level ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Level

Returns an integer between 0 (quiet) and 26 (loud).

WWAN Toolkit Programmer’s Reference Manual

35

Set the Speaker Volume Description:

This function sets the current audio gain level (volume) of the speaker. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL SetSpeakerVol( int Level ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Level

Returns an integer between 0 (quiet) and 26 (loud).

Increase the Speaker Volume Description:

This function increases the audio gain level (volume) of the speaker by 1. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

BOOL IncreaseSpeakerVol() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Decrease the Speaker Volume Description:

This function Decreases the audio gain level (volume) of the speaker by 1. Note: This function is not supported on devices with a data-only radio.

Method: Return Value:

36

BOOL decreaseSpeakerVol() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

WWAN Toolkit Programmer’s Reference Manual

Data Communication Functions This section describes the data communication functions.

Create a RAS Entry on Pocket PC Description:

This function creates a RAS connection entry. Note: If you intend to use Connection Manager, this function must be followed by the AddEntryToConnMgr() function. After completing the second function the new RAS connection appears in the Connection Manager.

Method:

Return Value:

DWORD CreateRasEntry( LPCTSTR lpszEntry, LPCTSTR lpszModem, int nBaudRate, DWORD nFlags, DWORD dwCountryCode, LPCTSTR lpszAreaCode, LPCTSTR lpszPhoneNo, LPCTSTR lpszExtraCmds, LPCTSTR lpszUserName, LPCTSTR lpszPassword, LPCTSTR lpszDomain, LPCTSTR lpszIPAddr, LPCTSTR lpszDNS, LPCTSTR lpszDNSAlt, LPCTSTR lpszWINS, LPCTSTR lpszWINSAlt ) The function returns 0 (zero) for successful or the error code as defined in the MSDN documentation. Parameter Descriptions Parameter

Description

lpszEntry

String containing the name of an entry in the connection manager, such as My GPRS Connection.

lpszModem

String specifying the name of the modem to be used by the data connection. On most Windows Mobile devices, this value should be “Cellular Line”.”

NBaudRate

Integer containing the baud rate suitable for the modem selected, such as 115200.

NFlags

Indicates whether software compression and/or IP compression should be used. The flags should be OR-ed together as normal. Possible values are: CRE_SWCOMP 1 CRE_IPCOMP 2

dwCountryCode

Country code of the location to be dialed. Use 0 for no country code, such as +44.

lpszAreaCode

String containing the area code of the location to be dialed. (NULL for no area code), such as 118.

lpszPhoneNo

String containing the complete phone number, typically 468777666 - Circuit switched (GSM/CDMA), *99# or *99***1# - Packet switched (GPRS), #777 - Packet switched (1xRTT).

lpszExtraCmds

String containing the additional dial string (extra AT commands), such as +CGDCONT=1,IP,my.apn.name. Additional dial string commands are not supported by all radios.

lpszUserName

String containing the username for the connection (NULL if not required).

lpszPassword

String containing the password for the username defined for the connection (NULL if not required).

WWAN Toolkit Programmer’s Reference Manual

37

Parameter Descriptions (continued) Parameter

Description

lpszDomain

String containing the domain for the connection (NULL if not required).

lpszIPAddr

String containing the fixed IP address of the device in dotted decimal format (NULL to use DHCP).

lpszDNS

String containing the fixed DNS address of the device in dotted decimal format (NULL to use DHCP).

lpszDNSAlt

String containing the alternative DNS address of the device in dotted decimal format (NULL to use DHCP).

lpszWINS

String containing the WINS address of the device in dotted decimal format (NULL to use DHCP).

lpszWINSAlt

String containing the alternative WINS address of the device in dotted decimal format (NULL to use DHCP).

Delete a RAS Entry From the Pocket PC Description:

Method: Return Value:

This function deletes a RAS connection entry from Pocket PC. The RemoveEntryFromConnMgr() function must be completed before this function is called. BOOL DeleteRasEntry( LPCTSTR lpszEntry ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszEntry

String containing the name of an existing RAS connection, such as My GPRS Connection.

Add a RAS Entry to the PocketPC Connection Manager Description: Method: Return Value:

This function adds an existing RAS entry to the connection manager. The function should follow the CreateRasEntry() function. BOOL AddEntryToConnMgr(LPCTSTR lpszDestination, LPCTSTR lpszEntry, BOOL bAlwaysDial) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions

38

Parameter

Description

lpszDestination

String specifying the name of an existing destination in the Connection Manager, such as My ISP.

lpszEntry

String containing the name of an entry in the connection manager, such as My GPRS Connection.

bAlwaysDial

Boolean value defining the state of the always dial flag in the selected connection manager destination. Default value is TRUE.

WWAN Toolkit Programmer’s Reference Manual

Remove a RAS Entry From the PocketPC Connection Manager Description:

Method: Return Value:

This function removes a RAS entry from the Connection Manager. After calling this function, call the DeleteRasEntry() function to completely remove the RAS entry from the device. BOOL RemoveEntryFromConnMgr( LPCTSTR szEntry ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

sZEntry

String specifying the name of an existing destination in the Connection Manager, such as My ISP.

Get Destination Information From PocketPC Connection Manager Description:

Method: Return Value:

This function gets information about a specified destination in connection manager. The function gives information on the number of RAS entries associated with the destination and the name of the entry with the ‘always dial’ flag set. BOOL GetConnMgrDestinationInfo( LPCTSTR lpszDestination, int *lpnEntries, LPTSTR lpszAlwaysDialEntry ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszDestination

String specifying the name of an existing destination in the Connection Manager, such as My ISP.

lpnEntries

Returns the number of RAS entries on the specified destination. Pass a NULL if this information is not required.

lpszAlwaysDialEntry

String containing the name of the entry that has the ‘always dial’ flag set. If there is no entry defined as ‘always dial’ within the destination specified, the string is empty. Pass a NULL if this information is not required.

Set the Default Dial RAS Entry for PocketPC Connection Manager Description: Method: Return Value:

This function sets the ‘always dial’ flag for a specified entry in a specified destination in the PocketPC Connection Manager. BOOL SetAlwaysDialEntry( LPCTSTR lpszDestination, LPCTSTR lpszAlwaysDialEntry ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszDestination

String specifying the name of an existing destination in the Connection Manager, such as My ISP.

WWAN Toolkit Programmer’s Reference Manual

39

Parameter Descriptions (continued) Parameter

Description

lpszAlwaysDialEntry

String containing the name of the entry to have its ‘always dial’ flag set.

Set Up a GPRS Context Description: Method:

Return Value:

This function sets up a GPRS context. This is not supported on CDMA networks. Data/header compression is not supported on Siemens MC45 or MC46. BOOL GPRSSetupContext( DWORD dwFlags, int ContextNumber, LPCTSTR APNName, LPCTSTR PDPAddress, BOOL HeaderCompression, BOOL DataCompression ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

dwFlags

Indicates which of the following parameters are used. The flags should be OR-ed together as normal. Possible values are: GPRSSETUPCONTEXT_APN 1 GPRSSETUPCONTEXT_PDPADDR 2 GPRSSETUPCONTEXT_DCOMP 4 GPRSSETUPCONTEXT_HCOMP 8

ContextNumber

Integer containing the identifier of the GPRS context (set of connection data) to be used. This is normally 1 but a GPRS radio can be set up with 3 different contexts. This can have the values 1 or 2.

APNName

String containing the APN (Access Point Name) for the GPRS network. For example MOBILE.02.CO.UK.

PDPAddress

String containing the PDP (Packet Data Protocol) address for the GPRS network. Note that this is not requesting a protocol type.

HeaderCompression

Set TRUE to compress the header information.

DataCompression

Set TRUE to compress the data.

Get the GPRS PDP Address Description: Method: Return Value:

40

This function gets the Packet Data Protocol address from the GPRS network if used. This is not supported on CDMA networks. BOOL GetGPRSPDPAddress( int ContextNumber, LPTSTR PDPAddress ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

WWAN Toolkit Programmer’s Reference Manual

Parameter Descriptions Parameter

Description

ContextNumber

Integer containing the identifier of the GPRS context (set of connection data) to be used. This is normally 1 but a GPRS radio can be setup with 3 different contexts. This can have the values 1 or 2.

PDPAddress

String containing the PDP (Packet Data Protocol) address.

Make a WWAN Connection Description:

This function makes a GPRS, 1xRTT or dialup connection. This function also pings the specified IP address to ensure that the connection is still open. Once the function is called, the toolkit receives callback information, if it is set up with the SetModemEventReporting function. This employs Connection Manager. Note: This is an asynchronous function. Monitor Connection Manager events to stay updated on status changes. Note: Using repeated PING functionality can be costly; please check with your network operator concerning data transfer charges.

Method: Return Value:

BOOL DoDialUpConnect( LPCTSTR ConnectionName, LPCTSTR IpAddresstoPing, int PingInterval, int PingTimeout ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ConnectionName

String specifying the name of the Connection Manager destination to use, such as My ISP.

IpAddresstoPing

String specifiying the IP address to ping periodically. If the ping operation is not desired (perhaps due to data transfer costs), then pass NULL or an empty string to disable the ping functionality.

PingInterval

Integer to determine the interval between successful pings (ms). Leave blank if ping is not required.

PingTimeout

Integer containing the maximum time the ping function waits to receive the ping reply (ms). Leave blank if ping is not required.

Make a WWAN Connection With Variable Ping Size Description:

This function is an extension of the DoDialUpConnect function above, which facilitates a variable ping size. Once the function has been called, the toolkit receives callback information, if it is set up with the SetModemEventReporting function. If you are using PocketPC 2002 or 2003, this uses Connection Manager. Note: This is an asynchronous function. Monitor Connection Manager events to stay updated on status changes.

WWAN Toolkit Programmer’s Reference Manual

41

Note: Using repeated PING functionality can be costly; please check with your network operator concerning data transfer charges. Method:

Return Value:

BOOL DoDialUpConnectEx( LPCTSTR ConnectionName, LPCTSTR IpAddresstoPing, int PingInterval, int PingTimeout, int PingSize ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ConnectionName

String specifying the name of the Connection Manager destination to use, such as My ISP.

IpAddresstoPing

String specifying the IP address to ping periodically. If the ping operation is not desired (perhaps due to data transfer costs), then pass NULL or an empty string to disable the ping functionality.

PingInterval

Integer to determine the interval between successful pings (ms). Leave blank if ping is not required.

PingTimeout

Integer containing the maximum time the ping function waits to receive the ping reply (ms). Leave blank if ping is not required.

PingSize

Integer containing the maximum size of the ping packet (bytes). Leave blank if ping is not required.

Terminate a GPRS, 1xRTT, or Dialup Connection Description: Method: Return Value:

This function ends a GPRS, 1xRTT, or dialup connection running on the device. BOOL DoDialUpHangup() The function returns a Boolean TRUE if successful or a Boolean FALSE if not.

Use RAS to Make a WWAN Connection Description:

This function makes a 1xRTT, GPRS, or dialup connection without using connection manager. This also pings the specified IP address to ensure that the connection is still open. Once the function is called, the toolkit receives RAS callback information, if it is set up with the SetModemEventReporting function. Note: This is an asynchronous function. Monitor RAS events to stay updated on status changes. Note: Using repeated PING functionality can be costly; please check with your network operator concerning data transfer charges. Note: Starting with Windows Mobile 6.0, Microsoft no longer supports the creation of data connections using the RAS API. As a result, this function is only supported on devices running Windows Mobile 5.0. Applications running on newer devices should use the Connection Manager functionality, like DoDialUpConnect() and DoDialUpHangup().

42

WWAN Toolkit Programmer’s Reference Manual

Header: Return Value:

BOOL DoRASConnect( LPCTSTR ConnectionName, LPCTSTR IpAddresstoPing, int PingInterval, int PingTimeout ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ConnectionName

String containing the name of the RAS connection to use, for example My Connection.

IpAddresstoPing

String specifying the IP address to ping periodically. If the ping operation is not desired (perhaps due to data transfer costs), then pass NULL or an empty string to disable the ping functionality.

PingInterval

Integer which determines the interval between successful pings (ms). Leave blank if ping is not required.

PingTimeout

Integer containing the maximum time the ping function waits to receive the ping reply (ms). Leave blank if ping is not required.

Use RAS to Make a WWAN Connection With Variable Ping Size Description:

This function makes a 1xRTT, GPRS, or dialup connection without using connection manager. This also pings the specified IP address to ensure that the connection is still open. Once the function has been called, the toolkit receives RAS callback information, if it is set up with the SetModemEventReporting function. Note: This is an asynchronous function. Monitor RAS events to stay updated on status changes. Note: Using repeated PING functionality can be costly; please check with your network operator concerning data transfer charges. Note: Starting with Windows Mobile 6.0, Microsoft no longer supports the creation of data connections using the RAS API. As a result, this function is only supported on devices running Windows Mobile 5.0. Applications running on newer devices should use the Connection Manager functionality, like DoDialUpConnect() and DoDialUpHangup().

Method:

Return Value:

BOOL DoRASConnectEx( LPCTSTR ConnectionName, LPCTSTR IpAddresstoPing, int PingInterval, int PingTimeout, int PingSize ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

ConnectionName

String containing the name of the RAS connection to use, for example My Connection.

IpAddresstoPing

String specifying the IP address to ping periodically. If the ping operation is not desired (perhaps due to data transfer costs), then pass NULL or an empty string to disable the ping functionality.

WWAN Toolkit Programmer’s Reference Manual

43

Parameter Descriptions (continued) Parameter

Description

PingInterval

Integer which determines the interval between successful pings (ms). Leave blank if ping is not required.

PingTimeout

Integer containing the maximum time the ping function waits to receive the ping reply (ms). Leave blank if ping is not required.

PingSize

Integer containing the maximum size of the ping packet (in bytes). Leave blank if ping is not required.

Terminate a RAS Connection Description:

This function ends a 1xRTT, GPRS or dialup RAS connection running on the device. Note: Starting with Windows Mobile 6.0, Microsoft no longer supports the creation of data connections using the RAS API. As a result, this function is only supported on devices running Windows Mobile 5.0. Applications running on newer devices should use the Connection Manager functionality, like DoDialUpConnect() and DoDialUpHangup().

Method: Return Value:

BOOL DoRASHangup() The function returns a Boolean TRUE if successful or a Boolean FALSE if not

Check Current WWAN Network Status Description:

This function sends a single ping to a user-specified IP address to determine if the Wireless Wide Area Network is available or not. This returns with the current status as soon as the ping has completed. Note: Using repeated PING functionality can be costly; please check with your network operator concerning data transfer charges. Note: To prevent interference with the USB connection, remove the device from the cradle before calling this function. Note: Be aware that not all networks permit ping packets beyond the gateway, which could result in incorrect feedback on the network status.

Method: Return Value:

WAN_PING_STATUS ActiveWwanAvailable ( LPCTSTR IpAddresstoPing, int PingTimeout, int PingSize ) The function values returned are: WAN_PING_STATUS: The resulting status of the ping to the specified IP address. WAN_AVAILABLE: Ping was successful WAN_UNAVAILABLE: Ping timed out WAN_NO_CONNECTION: No connection WAN_PING_ERROR: Ping failed

44

WWAN Toolkit Programmer’s Reference Manual

Parameter Descriptions Parameter

Description

IpAddresstoPing

String specifying the IP address of the server to ping.

PingTimeout

Integer containing the maximum amount of time the ping function waits to receive the ping reply (in ms).

PingSize

Integer containing the maximum size of the ping packet (in bytes).

Create a New Location to Dial From Description: Method:

This function creates a new dialing location in the connection settings. BOOL CreateDiallingLocation( LPCTSTR lpszLocation, LPCTSTRlpszAreaCode, LPCTSTR lpszCountryCode, bool bPulseDial, LPCTSTR lpszDisableCallWaiting, LPCTSTR lpszDialFmtLocal, LPCTSTR lpszDialFmtLongDist, LPCTSTR lpszDialFmtIntl, bool bOverwrite, bool bSetAsCurrent )

Return Value:

The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszLocation

String containing the name of the dialing location being created, such as GSM or GPRS.

lpszAreaCode

String containing the area code of the dialing location entry.

lpszCountryCode

String containing the country code of the dialing location entry.

bPulseDial

Boolean value where TRUE = pulse dial, FALSE = tone dial.

lpszDisableCallWaiting

String containing the dial string to disable call waiting. GSM has call waiting disabled during toolkit startup.

lpszDialFmtLocal

String containing the dialing format for local calls.

lpszDialFmtLongDist

String containing the dialing format for long distance calls.

lpszDialFmtIntl

String containing the dialing format for international calls.

bOverWrite

Set TRUE to ensure that we overwrite any existing location details set to TRUE.

WWAN Toolkit Programmer’s Reference Manual

45

Parameter Descriptions (continued) Parameter

Description

bSetAsCurrent

Set as TRUE to define this location as the current dialing location.

Delete an Existing Dialing Location Description: Method: Return Value:

This function deletes an existing dialing location. BOOL DeleteDiallingLocation( LPCTSTR lpszLocation ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszLocation

String containing the name of the dialing location being created, such as GSM or GPRS.

Set the Current Dialing Location Description: Method: Return Value:

This function sets the current dialing location. BOOL SetDiallingLocation( LPCTSTR lpszLocation ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszLocation

String containing the name of the dialing location being created, such as GSM or GPRS.

Get Connection Manager Settings for Device Network Card Description: Method: Return Value:

This function determines what the network card should connect to in Connection Manager. BOOL GetNetworkCardConnectsTo( CONNECTS_TO_TYPE *pConnectsTo ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Function values returned are: pConnectsTo: This can only be one of the following: CONNECTS_TO_UNKNOWN: The information requested was either corrupted or Connection Manager is not on the device. CONNECTS_TO_INTERNET: The network card is connecting to the internet settings defined in connection manager. CONNECTS_TO_WORK: The network card is connecting to the work settings defined in connection manager.

46

WWAN Toolkit Programmer’s Reference Manual

Set Connection Manager Settings for Device Network Card Description: Method: Return Value:

This function determines what the network card should connect to in Connection Manager. BOOL SetNetworkCardConnectsTo( CONNECTS_TO_TYPE ConnectsTo ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

pConnectsTo

This should only be one of the following: CONNECTS_TO_INTERNET: The network card is connecting to the internet settings defined in connection manager.

CONNECTS_TO_WORK: The network card is connecting to the work settings defined in connection manager.

Get Connection Statistics Description: Method:

Return Value:

This function obtains statistics about the current (or latest) connection. BOOL GetConnectionStatistics( DWORD* duration, DWORD* bytesTransmitted, DWORD* bytesReceived, DWORD* crcErrorCount, DWORD* timeoutErrorCount ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

duration

The duration time of the connection (in milliseconds).

bytesTransmitted

Number of bytes transmitted.

bytesReceived

Number of bytes received

crcErrorCount

The number of Cyclic Redundancy Check (CRC) errors

timeoutErrorCount

The number of timeout errors.

Error Handling Methods This section describes the error handling methods of the API.

Clear WWAN Error Code Description: Method:

This function resets the errorcode to 0 (WWANERRORCODE_NO_ERROR). VOID ClearWWANErrorCode()

WWAN Toolkit Programmer’s Reference Manual

47

Get Last WWAN Error Code Description: Method: Return Value:

Gets the latest error code. DWORD GetLastWWANErrorCode() The method returns a numerical error code. This can be used in a switch statement to determine the cause of the error. Note: Include the header file "WWANErrorCodes.h" in your project.

Note: A full list of error code descriptions can be found in “Get Last WWAN Error String” on page 48.

Get Last WWAN Error String Description: Method: Return Value:

This functions gets the latest error string. LPCTSTR GetLastWWANErrorString() The function returns a description of the error in plain English. Error Code Descriptions

48

Error Code

Description

0

WWANERRORCODE_NO_ERROR No error detected.

1001

WWANERRORCODE_NOT_SUPPORTED_ON_THIS_DEVICE The operation is not supported on this device.

1002

WWANERRORCODE_NOT_IMPLEMENTED_ON_THIS_DEVICE The operation is not implemented on this device.

1003

WWANERRORCODE_DEVICE_NOT_SUPPORTED The handheld device and/or wireless WAN radio is not supported by the toolkit.

1004

WWANERRORCODE_BAD_RADIO_IMPLEMENTATION Error detected in lower level radio interface.

3001

WWANERRORCODE_POWER_OFF The radio has not been powered on. Make sure you power on the radio before calling any other methods.

3002

WWANERRORCODE_TOOLKIT_NOT_SETUP The toolkit has not been set up properly.

3003

WWANERRORCODE_DLL_NOT_INITIALIZED On occurrence, please report to your Intermec representative.

WWAN Toolkit Programmer’s Reference Manual

Error Code Descriptions (continued) Error Code

Description

3004

WWANERRORCODE_EXTERNAL_LIBRARY_NOT_LOADED An external dependency could not be loaded. Make sure your operating system is supported by this version of the toolkit. The following OS’s are currently supported: • Windows Mobile 5.0 • Windows Mobile 6.1 • Windows Mobile 6.5

4002

WWANERRORCODE_PARAM_OUT_OF_RANGE One of your method arguments is out of range. This error would typically occur if you, for instance, try to read a phone book entry with index -1.

4003

WWANERRORCODE_INVALID_PARAM One of your arguments is invalid. Consult your manual concerning valid arguments and ranges.

4004

WWANERRORCODE_SMSFILE_MISSING The SMS File could not be located. Make sure the file is present by sending an SMS to the device. If you have changed the location see the “SMS Related Features” on page 28.

4005

WWANERRORCODE_END_OF_FILE This error occurs when you try to locate an entry (SMS) that does not exist.

4006

WWANERROCODE_PARAM_NULL A mandatory parameter was found to contain an empty string or a NULL value.

6001

WWANERRORCODE_BAD_IP Issued only when you try to ping 127.0.0.1. Use a valid server to ping.

6002

WWANERRORCODE_NO_NETWORK No network connection was found to complete the ping. Make sure you have a valid RAS or ConnMgr connection up and running.

6003

WWANERRORCODE_PING_FAILED Ping target could not be reached. Make sure your connection is valid and that the target is responding.

6004

WWANERRORCODE_CONNECTION_ERROR Could not connect to target. Make sure your IP address is valid and that your connection is up and running.

2001

WWANERRORCODE_PORT_ALREADY_OPENED

2002

WWANERRORCODE_PORT_OPEN_FAILED

2003

WWANERRORCODE_PORT_ERROR

2004

WWANERRORCODE_MODEM_READY_FAILED

The errors listed only occur at the moment when the radio is turned on and when the toolkit is set up: •

If these errors occur constantly, there might be something wrong with your wireless WAN device.

•

If any of these events happen once, try warm-booting the device.

WWAN Toolkit Programmer’s Reference Manual

49

If any of these errors occur on a regular basis, report it to your Intermec representative or Knowledge Central. Note: To aid Intermec support staff, you should run the Device Info tool and include the generated file in your correspondence with them.

Radio Information Features This section describes the radio information features of the API.

Get the Subscriber Identity Description:

Method: Return Value:

This function retrieves the International Mobile Subscriber Identity Number (IMSI) from the SIM card on devices operating on a GSM network. On devices operating on a CDMA network, this function retrieves the phone number associated with the radio. BOOL GetSubscriberID( LPTSTR SubscriberID ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

SubscriberID

String containing either the IMSI or the phone number, depending on the network carrier.

Get Radio Model Description:

Method: Return Value:

This function returns a DWORD representing the radio model of the device. Use the “RADIOMODEL_” constants defined in the wwantoolkit header file to determine device type. DWORD GetRadioModel () Possible return values: RADIOMODEL_UNSUPPORTED 0 RADIOMODEL_SIEMENS_MC45 1 RADIOMODEL_SIERRA_SB555 2 RADIOMODEL_SIERRA_EM3420 3 RADIOMODEL_SIEMENS_MC46 4 RADIOMODEL_SIEMENS_MC75 5 RADIOMODEL_SIERRA_EM5625 6 RADIOMODEL_SIEMENS_HC25 7 RADIOMODEL_QUALCOMM_115 8 RADIOMODEL_SIERRA_MC5728 9 RADIOMODEL_SIERRA_MC8795 10

50

WWAN Toolkit Programmer’s Reference Manual

RADIOMODEL_SIERRA_MC8355 11

Get Radio Type Description:

Method: Return Value:

This function identifies the network type used by the wireless WAN radio. For the purposes of this function, the base type is used. For example, UMTS and GRPS networks returns GSM, and 1xRTT networks returns CDMA. DWORD GetRadioType () Possible return values: RADIOTYPE_CDMA 0 RADIOTYPE_GSM 1 RADIOTYPE_UNKNOWN 2

Obtain the Serial Number of the Radio Description:

Method: Return Value:

This function retrieves the unique identifier for the wireless WAN radio present in the device. For devices operating on a GSM network, this function obtains the International Mobile Equipment Identifier (IMEI) from the modem. For most devices operating on a CDMA network, this function returns the Electronic Serial Number (ESN) from the modem. On the CN50 CDMA device, this function returns the Mobile Equipment Identifier (MEID). BOOL GetWWANRadioID( LPTSTR RadioID ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

RadioID

String containing the unique identifier for the radio.

Get the Manufacturer Identifier From the Radio Description: Method: Return Value:

This function interrogates the modem to obtain the manufacturer’s identifier. BOOL GetRadioManufactureIdent( LPTSTR Manufacturer ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

Manufacturer

String containing the manufacturer identifier held by the radio, for example SIEMENS.

WWAN Toolkit Programmer’s Reference Manual

51

Get the Model Identifier for the Radio Description:

Method: Return Value:

This function determines the model number of the radio in the device. To get full radio type information, use the GetRadioManufactureIdent() function as well as this one. BOOL GetRadioModelIdent( LPTSTR RadioIdent ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

RadioIdent

String containing the model name of the radio, such as MC45.

Determine the Firmware Version on the Radio Description: Method: Return Value:

This function determines what firmware version is on the radio. Use can this information to confirm that the device is running the latest firmware version. BOOL GetRadioRevisionNumber( LPTSTR RevisionIdent ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

RevisionIdent

String containing the firmware revision number of the radio, such as 1.03.01.

Get the Phone Number Description:

Method: Return Value:

This function retrieves the device phone number. For devices operating on GSM networks, the phone number is normally stored on the SIM card. Not all SIM cards can store and/or report tthe phone number, so this functionality cannot be guaranteed. For devices operating on CDMA networks, the phone number is assigned by the cellular carrier. As a result, the phone number should always be available after a device is registered with the provider. BOOL GetPhoneNumber( LPTSTR PhoneNumber ) The function returns a Boolean TRUE if a phone number was found or a Boolean FALSE if not. Parameter Descriptions

52

Parameter

Description

PhoneNumber

The unit’s phone number.

WWAN Toolkit Programmer’s Reference Manual

Determine the Radio Capabilities Description: Method: Return Value:

This function retrieves information on the various features supported by the radio hardware. int GetRadioCapabilities() The function returns one or more of the following values. Values are combined via a bitwise oroperation. If an error occures, this function returns 0. WWANTK_RADIOCAPS_SUPPORTSDATA: Indicates that the radio hardware supports data connection functionality. Currently, all of the radios supported by the WWAN Toolkit include this feature. WWANTK_RADIOCAPS_SUPPORTSVOICE: Indicates that the radio hardware supports voice call functionality, such as placing phone calls, adjusting volume levels, and storing contact information in the phone book. Radios that do not support these features are considered “data-only” radios. WWANTK_RADIOCAPS_SUPPORTSCARRIERSELECTION: Indicates that the radio hardware supports the ability to change network carriers at run time. Currently, only devices with a Flexible Network Radio support this feature.

Carrier Selection Functions This section describes how to identify and change network carriers on devices that support Flexible Network Radio.

Get the Current Carrier Selection Description:

This function retrieves the currently selected network carrier, such as “Sprint” or “Generic UMTS”. Note: This function is only supported on devices that have a Flexible Network Radio, such as the Sierra MC8355.

Method: Return Value:

BOOL GetCurrentCarrier(LPTSTR lpszCarrier, int nSize) The function returns a Boolean TRUE if the network carrier information is retrieved or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszCarrier

String containing the name of the current network carrier.

nSize

Integer containig the size of the string buffer (in characters).

WWAN Toolkit Programmer’s Reference Manual

53

Set the Current Carrier Selection Description:

This function instructs the radio to switch to the specified network carrier, such as “Sprint” or “Generic UMTS”. The GetSupportedCarriers() and GetNextSupportedCarrier() functions determine which carriers are available. This function resets the radio to change carriers. As a result, calling this function terminates any existing data connections. This function can take up to 30 seconds to execute because radio power is cycled during the reset process. When switching to a GSM network, applications should use one of the network selection functions, such as AutomaticNetworkRegister() to register with the new network before attempting to establish a data connection. Note: This function is only supported on devices that have a Flexible Network Radio, such as the Sierra MC8355.

Method: Return Value:

BOOL SetCurrentCarrier(LPCTSTR lpszCarrier) The function returns a Boolean TRUE if the network carrier is changed or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszCarrier

String specifying the network carrier to select.

Get the Supported Carriers Description:

This functions creates a list of all the network carriers that are supported by the radio. Call this function before the GetNextSupportedCarrier() function, which reads the entries in the list. This list depends on both the radio hardware and the region supported by the device. For example, a CN70 with a Sierra MC8355 radio supports the “ATT”, “Generic UMTS”, “Sprint”, and “Verizon” carrier options when configured for sale in North America, but supports only the “Generic UMTS” carrier option when configured for ETSI. Note: This function is only supported on devices that have a Flexible Network Radio, such as the Sierra MC8355.

Method: Return Value:

54

BOOL GetSupportedCarriers () The function returns a Boolean TRUE if the list is generated or a Boolean FALSE if not.

WWAN Toolkit Programmer’s Reference Manual

Get the Next Supported Carrier From the Carrier List Description:

This functions retrieves network carrier information from a list of supported carriers. Use the GetSupportedCarriers() function to build the list before calling this function. To get the entire list of supported carriers, call this function repeatedly until it indicates there are no more entries (by returning FALSE). Note: This function is only supported on devices that have a Flexible Network Radio, such as the Sierra MC8355.

Method: Return Value:

BOOL GetNextSupportedCarrier(LPTSTR lpszCarrier, int nSize) The function returns a Boolean TRUE if the carrier information is retrieved or a Boolean FALSE if not. Parameter Descriptions Parameter

Description

lpszCarrier

String specifying the name of the next supported network carrier.

nSize

Integer containig the size of the string buffer (in characters).

Versioning This section describes versioning functions.

Get WWAN Toolkit Version Description: Method: Return Value:

The function returns the version information for the Wireless WAN Toolkit dll on the device. BOOL GetWWANToolkitVersion( int *major, int *minor, int *revision, int *build ) The function returns a Boolean TRUE if successful or a Boolean FALSE if not. Return values are: •

major: Integer showing the major build number of the onboard toolkit dll.

•

minor: Integer showing the minor build number of the onboard toolkit dll.

•

revision: Integer showing the revision build number of the onboard toolkit dll.

•

build: Integer showing the build number of the onboard toolkit dll.

WWAN Toolkit Programmer’s Reference Manual

55

Worldwide Headquarters 6001 36th Avenue West Everett, Washington 98203 U.S.A. tel 425.348.2600 fax 425.355.9551 www.intermec.com © 2011 Intermec Technologies Corporation. All rights reserved.

WWAN Toolkit Programmer’s Reference Manual

*937-013-003* P/N 937-013-003