brewsdkuser'sguide

QUALCOMM Incorporated5775 Morehouse Drive

San Diego, CA. 92121-1714U.S.A.

This manual was written for use with the BREW SDKTM for Windows, software version 1.1.0. This manual and the BREW SDK software described in it are copyrighted, with all rights reserved. This manual and the BREW SDK software may not be copied, except as otherwise provided in your software license or as expressly permitted in writing by QUALCOMM Incorporated.

Copyright 2001 QUALCOMM Incorporated

All Rights Reserved

Printed in the United States of America.

All data and information contained in or disclosed by this document are confidential and proprietary information of QUALCOMM Incorporated, and all rights therein are expressly reserved. By accepting this material, the recipient agrees that this material and the information contained therein are held in confidence and in trust and will not be used, copied, reproduced in whole or in part, nor its contents revealed in any manner to others without the express written permission of QUALCOMM Incorporated.

Export of this technology may be controlled by the United States Government. Diversion contrary to U.S. law prohibited.

Binary Runtime Environment for Wireless, BREW, BREW SDK, TRUE BREW, BREWStone, MobileShop, Eudora, and PureVoice are trademarks of QUALCOMM Incorporated.

QUALCOMM is a registered trademark and registered service mark of QUALCOMM Incorporated.

Microsoft, Windows, Visual Studio, and Sound Recorder are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Macintosh is a registered trademark of Apple Computer, Inc.

UNIX and X-Windows are trademarks of The Open Group.

Adobe, Acrobat, and Photoshop are trademarks of Adobe Systems Incorporated.

All trademarks and registered trademarks referenced herein are the property of their respective owners.

BREW SDK User’s Guide

December 13, 2001

iii

Contents

Introducing the BREW SDK User’s Guide, 7

BREW documentation, 8Documentation conventions, 9Using online manuals, 9

Links, 10Table of contents and indexes, 10Printing, 10Searching for information in BREW documents, 10Getting additional help for using the Acrobat Reader, 11

BREW acronyms and terms, 11Requesting new BREW features, 15For more information, 15

BREW SDK Overview, 16

Installing the BREW SDK, 16Components of the BREW SDK, 17

How the components interact, 18BREW SDK directory structure, 20

Device files, 20Examples directory, 21

Sample applications, 22The en (system resources) subdirectory, 22Shared files, 22

Bitmaps directory, 23Applet directory, 23MIF directory, 23Resource directories, 24About paths and filenames, 25

Contents

iv

BREW Basics, 26

The BREW solution, 26BREW advantages, 26The BREW environment, 28

BREW module/interface structure, 30Using an interface, 30

Becoming an authenticated BREW application developer, 30

BREW Programming Concepts, 32

Overview of applets and modules, 32About MIFs, 33BREW ClassIDs, 34

Interface ClassIDs, 34Applet ClassIDs, 36

Creating instances, 36Creating applets, 37Processing applet events, 37Suspending and resuming an applet, 38

Monitoring incoming SMS messages, 39Directed SMS messages, 39How BREW processes incoming SMS messages, 40

Creating new applications, 40Language-specific system resources, 41Floating-point operations, 41

Building BREW applications for wireless handsets, 42ARM Development Suite 1.0.1, 42ARM Development Suite 1.1, 46ARM BREW Builder, 47

Comparing ARM BREW Builder and ARM Development Suite 1.1, 47Accessing shell services, 48

IShell interface, 48IBase interface, 49IModule and IApplet interfaces, 49

IModule interfaces, 49IApplet interface, 50

Events passed to an applet, 50Tips for event handling, 51BREW key event dwParam structure, 52Embedded File System, 53

Contents

v

BREW Sample Applications, 54

Sample demonstration applications, 55Sample usage applications, 59Sample 1: "Hello World", 66

Source code for Sample 1, 67Sample 2: Using resources, 71

Source code for Sample 2, 72Sample 3: Using timers and alarms, 79

Source code for Sample 3, 79Sample 4: Using files, 83

Source code for Sample 4, 84Sample 5: Using databases, 85

Source code for Sample 5, 86Sample 6: Using sockets, 88

Using Dialogs and Controls, 89

Creating dialogs, 89Using the Resource Editor to create a dialog, 89Constructing the dialog manually, 91

Dialog events, 92Dialog controls, 92Terminating dialogs, 93

Dialog application example, 93

Using the BREW Emulator, 97

Running the Emulator, 97Emulator menus and other features, 99

File menu, 100View menu, 102Tools menu, 102Help menu, 104Backlight toggle, 104Color support in the Emulator, 104

Running sample applications, 105Viewing and editing the application source code, 107Using the Application Manager, 108Using speed emulation, 112

Configuring devices for speed emulation, 112Tuning speed emulation parameters and enabling the device, 113

Contents

vi

Using TAPI emulation, 114Handling calls incoming to BREW, 114Handling incoming SMS messages, 115Handling calls outgoing from a BREW application, 117

Extending BREW APIs, 119

Declaring the interface, 119Defining the class, 120Defining the class functions, 121Extension Usage, 124

Using Visual Studio Add-Ins, 125

BREW Application Wizard add-in, 125Automated ARM compiling add-in, 130

Appendix A: SDK Software Backward Compatibility, 133

Appendix B: Event Codes and Key Codes, 135

Event codes, 135Key codes, 137

Appendix C: Problems and Warning Messages, 139

Emulator problems, 140Emulator messages, 141

Applet-specific messages, 142Configurator problems, 143Configurator messages, 144MIF Editor messages, 146Resource Editor messages, 147

Index, 152

7

Introducing the BREW SDKUser’s Guide

Binary Runtime Environment for Wireless™ (BREW™) is a standard environment for

applications development for wireless handsets The BREW application developer’s most

important tool is the BREW Software Development Kit (BREW SDK™). This guide provides an

overview of the BREW SDK, and is divided in the following sections:

BREW SDK Overview Provides an overview of BREW SDK concepts and components, including a description of how the SDK is organized.

BREW Basics Provides an overview of BREW and describes how the BREW Application Execution Environment (AEE) allows you to efficiently develop applications that can be ported to virtually any handheld device. This section also includes a brief introduction to the BREW APIs. See the BREW API Reference for detailed descriptions of each of the BREW API functions, including parameter types and return values.

BREW Programming Concepts Explains basic and advanced concepts of the BREW SDK, including modules, applets, and interfaces.

BREW Sample Applications Provides several sample applications developed using the SDK and guides you through the steps involved in developing an application.

Using Dialogs and Controls Describes and explains how to use dialogs and controls in your BREW applications.

Using the BREW Emulator Describes how to start and use the Emulator to load and test your applications. This section also explains how the Emulator can help you learn about the BREW environment.

Extending BREW APIs Provides information on customizing BREW APIs with extensions.

Using Visual Studio Add-Ins Describes add-ins to Microsoft Visual Studio, provided with the BREW SDK, that can make your development efforts more efficient.

Appendix A: SDK Software Backward Compatibility

Describes SDK software compatibility issues you may need to be aware of if you have downloaded multiple versions of the SDK software.

8

Introducing the BREW SDK User’s Guide

BREW documentation

This guide is part of an information set that includes the following documents:

Appendix B: Event Codes and Key Codes

Lists event codes and key codes supported by BREW.

Appendix C: Problems and Warning Messages

Lists possible problems or messages you may encounter while using BREW, and provides resolution suggestions.

BREW SDK User’s Guide Introduces the components of the BREW Software Development Kit (BREW SDK™) and their relationship to one another. The document also contains general instructions for developing BREW applications and for using the Emulator.

BREW API Reference Provides information about BREW functions and data structures needed to develop applications for BREW-enabled mobile platforms.

BREW Device Configurator Guide Describes how to use the BREW Device Configurator to create effective wireless devices for emulation by the BREW Emulator.

BREW Resource Editor Guide Describes how to use the BREW Resource Editor to create the text strings, images, and dialogs used by BREW applications.

BREW MIF Editor Guide Describes how to use the BREW MIF Editor to create and modify Module Information Files (MIF)—a special type of BREW resource file that contains information about the classes and applets supported by particular BREW modules.

BREW SDK Utilities Guide Describes how to use the utilities, such as the PureVoice Converter, included with the BREW SDK.

BREW Compressed ImageAuthoring Guide

Describes how to use the BREW Compressed Image Authoring Tool to create files for displaying and animating images in your applications.

9


Documentation conventions

Several of the conventions used throughout the BREW documentation are illustrated in the

following example:

Procedures are preceded by a line of blue text

1. Choose Start > Programs > BREW > BREW Emulator. This, of course, is

shorthand for “Click the Windows Start button, point to Programs, then to BREW,

and click BREW Emulator.” The BREW documentation uses bold text to indicate

options that you should select.

Italic text following a numbered step identifies what happens after you have performed the step, such as: The BREW Emulator window opens and BREW

automatically runs the BREW Application Manager.

NOTE: As you can see in step 1 in the previous example, the BREW documentation describes

the use of menu options as the means for navigating through the BREW software. In many

instances, you can perform the same action using a number of methods, such as choosing a

menu option, clicking a toolbar button, pressing shortcut keys on the keyboard, and right-

clicking to open a shortcut menu. You will, no doubt, discover ways of getting around that are

the most comfortable to you. But rather than document ALL of the ways you can perform each

task, the BREW manuals generally describe only one way.

Programming code appears in the manuals like this:

#include "AEEModGen.h" // Module interface definitions#include "AEEAppGen.h" // Applet interface definitions#include "AEEDisp.h" // Display Interface definitions#include "helloworld.bid" // Applet ClassID

Using online manuals

The BREW online manuals are available for viewing and printing using the Adobe Acrobat

Reader. This subsection describes several suggestions that will help you get the most out of

this documentation.

10


Links

Links appear in the BREW online manuals as blue text; for example, Introducing the BREW

SDK User’s Guide. Point your mouse at the blue link and notice that the cursor changes.

Clicking on the link takes you to a different location in the document. If you want to return to

your starting place, choose Document > Go to Previous View.

Table of contents and indexes

The table of contents at the start of each manual and the index at the end of each manual

perform the same function as other links. Simply browse the contents or index until you find

the entry that you want to view, and click the entry.

Printing

Printing pages from an online manual, or printing the entire online manual, is much the same

as printing in any word processing program. Simply choose File > Print, select a range of

pages, and click Print. The page number at the bottom of the Acrobat Reader (for example,

5 of 100) corresponds to the page number in the BREW manual.

Searching for information in BREW documents

The Acrobat Reader allows you to search for a word or a string of words in the currently

opened manual.

To find information in a BREW online manual

1. If the manual is not already opened, choose Start > Programs > BREW > BREW

Docs, and click the manual you want view.

The Acrobat Reader opens the manual.

2. Choose Edit > Find.

3. Type the word or string of words you want to find and click Find.

The first instance of the selected word or string of words is highlighted in the manual.

4. To find the next instance of the word or string of words, click Find Again.

11


NOTE: This Search feature is not a full-text search. That is, if you type How do I

configure an applet to play sound?, the system will not search for

individual words in the string; it will search for the exact string of words you typed.

So it is usually a good idea to type as few words as needed to find the information

you seek.

5. Click to highlight the book you want to open, and click View.

The selected book opens and the first instance of the word or words is highlighted.

6. To find the next instance of the word or words, choose Edit > Search > Next.

Getting additional help for using the Acrobat Reader

The Adobe Acrobat Reader includes a comprehensive online help system. To learn how to

perform a particular action, simply choose Help > Reader Help and search the online help for

the desired topic.

BREW acronyms and terms

The following acronyms and terms are used throughout the BREW documentation set.

Active device A set of files consisting of a resource file (.qsc extension) and device image files (.bmp extension), interpreted by the Emulator to emulate the device. The Device Configurator creates the resource file.

ADS Application Download Server

AEE Application Execution Environment

ANSI American National Standards Institute

APCS ARM Procedure Call Standard

API Application Programming Interface

Applet A class that supports the base IApplet interface. This interface is used by the BREW AEE to load an applet, dispatch events, and terminate an applet. In this document, it is also used synonymously with the word “application.”

ARM Advanced RISC Machines

ASCII American Standard Code for Information Interchange

ASIC Application-specific integrated circuit

12


BAR BREW Applet Resource. The binary output file from the Resource Editor.

BCI BREW Compressed Image. A BCI file consists of a series of graphic images compressed and combined, using the BREW Compressed Image Authoring Tool, to add animation to a BREW application.

BDS BREW Distribution System

BMP Bitmap

Bounding rectangle Each device object, regardless of its shape, is bounded by a rectangle, as represented in Windows pixel coordinates.

BREW Binary Runtime Environment for Wireless. BREW is an efficient application development environment that is layered upon public services offered by mobile ASICs.

BREW AEE BREW Application Execution Environment. The BREW AEE is the environment that allows BREW applets to be loaded and run.

BREW SDK BREW Software Development Kit. This allows application developers to quickly write and test applets and modules in a familiar Windows desktop environment.

BREW test plan The BREW test plan is a set of testing guidelines that help application developers test their applications thoroughly.

BRI BREW Resource Intermediate. This is the intermediate resource file produced by the Resource Editor before it is compiled into a BAR file.

CDMA Code Division Multiple Access

CGT BREW Code Generation Tool

Class A template (file) that defines the generic characteristics of an object or module in the system.

ClassID 32-bit IDs for identifying BREW classes and applets. These IDs are assigned at the site www.qualcomm.com/brew/sdk/classid. BREW ClassIDs are available to authenticated developers only.

Device In the context of the Emulator, an image of a mobile phone faceplate.

Device attributes The attributes pertaining to the wireless device, such as model and pushed image file.

DLL Dynamic-link library

DTMF Dual Tone Multi-Frequency

EFS Embedded File System

GPS Global Positioning System

GUI Graphical user interface

http://www.qualcomm.com/brew/sdk/classid

13


HTTP Hypertext Transfer Protocol

IDE Integrated Development Environment

Image file A file containing an image of the device. It is created by a third party, for example, a carrier or application developer.

Interface An abstract class providing a set of methods for a specific service. For example, the IDisplay interface provides a set of methods for basic display services. Each interface has a unique class identifier (AEECLSID), and the name of each interface begins with the letter “I.” In BREW, all the interfaces are derived from a base level class interface called IBase. IBase consists of two standard methods for incrementing and decrementing the reference count of an object. This reference count mechanism allows an object to be shared by multiple users.

IP Internet Protocol

ISO International Organization for Standardization

Key object attributes Attributes pertaining to the screen object, such as key symbols, key action, and overload codes.

Large font The Emulator uses this device attribute to show text on the screen. The large font maps to AEE_FONT_LARGE. Its bold version is not used.

Logical screen size The size of the device screen measured in Windows pixels.

Method An entry point into an object that allows it to interact with other objects or applets.

MIDI Musical Instrument Digital Interface

MIF Module Information File. The MIF Editor generates this binary file, which contains information regarding the list of classes and applets supported by the modules.

MIME Multipurpose Internet Mail Extensions

Module In the BREW model, a library or dynamically loaded code block that exposes one or more interfaces. As each interface is associated with an ID, the module can expose these interfaces in a generic manner. This eliminates the need for explicit entry points in modules for each exported interface.

MP3 MPEG Audio Layer-3

MSM Mobile Station Modem

Normal font The Emulator uses this device attribute to show text on the screen. The normal font maps to AEE_FONT_NORMAL, and its bold version maps to AEE_FONT_BOLD.

Object An instance of a class that provides a specific service.

14


OEM Original equipment manufacturer

PDA Personal digital assistant

Physical screen size The size of the device screen measured in inches or centimeters.

PNG Portable Network Graphics

Primary code A code that uniquely identifies the primary functionality of a device object. Each device object has only one associated primary code. It is assigned from a pool of available virtual codes. Key and screen objects have their own pools of virtual codes.

Pushed bitmap file An optional file containing an image of a device skin with all buttons pushed. The Emulator uses this image to animate button push action. If it is not present, the Emulator emulates button push action by inverting the color. A third party, such as a carrier or applications developer, creates this file.

QCP PureVoice files supported by the Emulator and BREW applications. For more information, see the BREW SDK Utilities Guide.

RAM Random access memory

Resource Editor A tool that generates the resources for applications.

Resource file A file containing active resource information. The Emulator and Device Configurator interpret this file, in conjunction with image files.

Resources Elements used in applications and/or libraries. In BREW, three types are supported: string, image, and dialog.

Screen object attributes

Attributes pertaining to a screen object, such as pixels per row, pixels per column, and physical width and height.

SDI Single document interface

SDK Software development kit

SDT Software development toolkit

SMS Short message service

TAPI Telephone application programming interface

TCP/IP Transmission Control Protocol/Internet Protocol

WAV Waveform

Wide string A character string composed of 16-bit characters. Wide strings are used for character encodings, such as Unicode that require more than 8 bits per character.

15


Requesting new BREW features

Do you have ideas for features that would make the BREW SDK more valuable and useful to

you? If so, send us email at [email protected]. Each request is evaluated, and a

member of the New Features Response Team will respond to your email.

For more information

Online information and support is available for BREW application developers. Please visit the

BREW web site for details: www.qualcomm.com/brew/developer.

http://www.qualcomm.com/brew/developer

mailto:[email protected]?subject=BREW%20Features%20Request

16

BREW SDK Overview

The BREW SDK comprises a suite of tools and services that allow application developers to

quickly, efficiently, and cost-effectively develop and deploy new applications for a wide variety

of handheld devices.

Installing the BREW SDK

If you haven’t already done so, load the BREW SDK from the BREW SDK CD or download it

from www.qualcomm.com/brew. To install the BREW SDK from the CD, insert the CD into your

computer’s CD-ROM drive. The installer starts automatically. If necessary, see the Readme

file on the CD for detailed installation instructions.

The minimum system requirement for installing the BREW SDK is Microsoft Windows NT 4.0

SP3 or higher, or Windows 2000 SP2 or higher. To develop applications using the BREW SDK,

you also need Microsoft Visual C++ 6.0 or higher.

NOTE: Do not install the BREW SDK in a directory whose name contains dots (for example,

<BREW.1.1.>). The BREW SDK emulates file systems on mobile devices, and these file

systems do not recognize a dot as a valid character in a directory name.

http://www.qualcomm.com/brew

17

BREW SDK Overview

Components of the BREW SDK

Here’s what’s included in the BREW SDK:

BREW AEE The BREW AEE is a fully extensible, object-oriented application development and execution environment. This provides a platform on which to develop applets and shared modules in C or C++. A familiar, event-driven architecture (similar to Microsoft Windows, Macintosh, or X-Windows) enhances usability.

Emulator The BREW EmulatorTM, subsequently referred to as the Emulator, is the front-end graphical user interface (GUI) used to load and test your applets. Several preconfigured device emulations are provided. See Using the BREW Emulator for more information. You can also create your own device emulations using the Configurator. For detailed instructions on using the Device Configurator, see the BREW Device Configurator Guide.

Device Configurator Use the BREW Device ConfiguratorTM, subsequently referred to as the Configurator, to generate new devices or edit existing configurations. This is helpful for configuring features such as keypad keys and their functions, screen dimensions and resolution, and memory size. For detailed instructions on using the Configurator, see the BREW Device Configurator Guide.

Resource Editor Use the BREW Resource EditorTM, subsequently referred to as the Resource Editor, to create resources for applications. You can use the same resource files in Windows and in the device. For more information about using the Resource Editor, see the BREW Resource Editor Guide.

MIF Editor The BREW MIF EditorTM, subsequently referred to as the MIF Editor, generates Module Information Files (MIF) which contain module- and applet-specific information required to load the applet. For more information about using the MIF Editor, see the BREW MIF Editor Guide.

BREW DLLs BREW contains several dynamic-link libraries (DLL) that expose the core supported BREW classes in the Microsoft Windows environment. Because the DLLs use the identical code developed for BREW, there is little difference between application behavior in the Windows-based BREW Emulator and on a live device.

Win-OEM DLLs Win-OEM DLLs provide the underlying layers required to emulate device behavior on a Windows platform.

BREW header files BREW header files contain the BREW interface definitions, and are used to develop applets. Each BREW interface has an associated header file, and each applet must contain the header file of each interface used by that applet.

Visual Studio add-ins Free add-ins to Microsoft Visual Studio automate some of the time-consuming tasks you perform in Visual Studio to develop BREW applications.

18

BREW SDK Overview

How the components interact

The diagram that follows shows you the main elements of the BREW SDK (MIF Editor,

Resource Editor, C++ IDE, Device Configurator, and Emulator) and how they interact with one

another.

NOTE: In the diagram, fooapp represents an application developed with BREW.

BREW utilities Utilities, included with the BREW SDK, provide added functionality to your BREW applications.

Sample applications Sample application DLLs and their source code provided with the SDK include the following:

• Calculator

• Calendar

• Clock applications (stopwatch, countdown, alarm clock)

• Games

• Memo Pad

• MIDI-MP3 Player

• Usage applications (to illustrate how BREW interfaces can be used)

Documentation The entire BREW documentation set is available from within the BREW development environment.

19

BREW SDK Overview

NOTE: As indicated in the diagram, each of the elements in the BREW SDK are described in

the other manuals included with the SDK, with the exception of the Emulator. For more

information on the Emulator, see Using the BREW Emulator in this guide.

fooapp

ClassIDs:Request fromQUALCOMM

website

Reference:BREW MIF Editor Guide

Reference:BREW Resource

Editor Guide

ApplicationDeveloper

BREW Resource EditorInput

StringsBitmapsDialogs & controls

Outputfooapp.bar, fooapp_res.hfooapp2.bar, fooapp2_res.h, ...

Location:BREW \fooapp\

BREW \fooapp\Location

fooapp Project in MSVC++IDE(fooapp.dsp fooapp.dsw)

Input

Output

AEEAppGen.c, AEEAppGen.hAeeModGen.c, AeeModGen.hfooapp.c, fooapp.h, fooapp_res.h

fooapp.dll

Reference:BREW Device

Configurator Guide

Emulates the device in BREW environment. The developer can load and test applets and classes contained in fooapp.

BREW Emulator

OEM

Most likely (see Note)

BREW MIF Editor

InputSupported classes and appletsApplet titles, icons, thumbnailsExported classesDependanciesNotificationsBREW privileges

For example: BREW\Examples\ MIF\Apps\256colors

Preferred LocationBREW MIF Directory

Outputfooapp.mif

BREW APIReference

Reference:BREW Sample

Apps

BREW SDK User's Guide

Reference:BREW SDKUser's Guide

BREW Device ConfiguratorInputDevice bitmap. SampleDevice.bmpDevice objects and attributes:Keys and key codesScreen, screen dimensions, pixelsLanguage and fontsDevice heap sizeModel namePushed device bitmap

Output

Preferred location:

Device res. file: SampleDevice.qsc

BREW\Devices

Note: Sample devices are shipped with theBREW SDK. Usually, OEMs create devices and Application Developers need not createthem.

20

BREW SDK Overview

BREW SDK directory structure

The root directory of the BREW SDK directory structure is <BREW>. It contains the following

directories:

Device files

A set of predefined sample device files is provided with the BREW SDK. Each sample device

file can be loaded in the Emulator to show a different device skin, as illustrated below. See

Using the BREW Emulator on page 97 for information on loading device files in the Emulator.

Directory Contents

Bin BREW SDK binaries and data files. The <Bin\DataFiles> directory contains the tone database and beep types for the Emulator. For details, see the ISound interface description in the BREW API Reference.

Bitmaps Images used in the sample applications. They are stored in the Mono, 4Grey, and 256color directories. For more information, see Bitmaps directory on page 23.

Devices Predefined sample device files that you can load in the Emulator. For more information, see Device files below.

Docs BREW SDK online documentation.

Examples Sample applications, application resources, BAR files (created by the Resource Editor to load images into an application’s DLL), shared files, and MIFs. (For more information, see Examples directory on page 21.) The Emulator uses components of this directory to load and execute applications.

Inc BREW AEE header files that can be used in BREW modules.

Readme Release, license, and contact information.

Src BREW application-related foundation source files. You must include AEEAppGen.c and AEEModGen.c in the project or build of every application, unless you have created customized versions of these files.

21

BREW SDK Overview

NOTE: The BREW SDK provides the ability to create new devices via the Configurator. See

the BREW Device Configurator Guide for detailed instructions on creating new devices.

Examples directory

The Examples directory contains sample applications, application resources, BAR files (used

by the Resource Editor to load images into an application’s DLL), shared files, and MIFs. The

Emulator uses components of the Examples directory to load and run applications.

22

BREW SDK Overview

Sample applications

The BREW SDK is shipped with a set of sample applications. These applications are found in

the <BREW\Examples> directory. Sample applications are of two types:

For descriptions of demonstration and usage sample applications included in the BREW SDK,

see BREW Sample Applications on page 54.

NOTE: The usage applications included with the BREW SDK demonstrate how to use BREW

interfaces and APIs; however, they do not represent examples of TRUE BREW™ tested code.

The en (system resources) subdirectory

The <BREW\Examples\en> directory is the default resource directory for the English

language. It contains system and application resources for color depths of 1-bit, 2-bit, and 8-

bit under the Mono, 4Grey, and 256color directories. See Resource directories on page 24 for

details.

Shared files

The <BREW\Examples\shared> directory contains images, MIDI files, QCP files, and MP3

files used by the Application Manager within the Emulator. This directory also contains a text

file called appinfo.txt. Whenever a change is made in the Application Manager, such as when

a new image is assigned to an application, the change is written to this file. When the Emulator

is started the next time, the system reads this file, along with the specified MIF directory, and

loads the correct configuration into the Application Manager. See Using the Application

Manager on page 108 for more information.

Demonstration applications

These applications demonstrate the capabilities of various components of BREW, including the hello world application, games, scheduler, calculator, alarm clock, stopwatch, text memo, and MIDI-MP3 player. These applications are also intended to act as references and starting points for developing new applications. For information of running these sample applications, see Using the BREW Emulator on page 97.

Usage applications These applications demonstrate how to use BREW interfaces and APIs. The names of most of these applications begin with an I. For example, IMenuCtl application shows you how to use the BREW IMenuCtl interface to manage menus in a BREW application.

23

BREW SDK Overview

Bitmaps directory

The <BREW\bitmaps> directory contains images used in the sample applications. They are

stored in the Mono, 4Grey, and 256color directories. You can add files to this directory to use

new images in your applications.

Applet directory

The default applet directory is <BREW\Examples>. You can change the default by selecting a

different directory in the Brew Emulator Settings dialog box (Tools > Settings).

The applet directory represents the root directory under which application directories are

stored. Each application has its own directory with the same name as its MIF and the

application executable must reside in the application directory. For example, the MIDI.MIF file

must have a corresponding subdirectory called MIDI under the applet directory

<BREW\Examples>. Inside this subdirectory is the DLL corresponding to the module. The

MIDI subdirectory contains the file MIDI.DLL. This subdirectory may also contain resource files

and other data files associated with all the applications within that module.

MIF directory

All MIFs reside in the directory <BREW\Examples\MIF>, which is organized as follows:

• The <BREW\Examples\MIF\Apps> directory contains the MIFs of all the

demonstration applications.

• The <BREW\Examples\MIF\Usage> directory contains the MIFs of all the usage

applications.

Within the <BREW\Examples\MIF\Apps> and <BREW\Examples\MIF\Usage> directories, the

MIFs are stored for color depths of 1-bit, 2-bit, and 8-bit under the Mono, 4Grey, and 256color

directories, respectively. For example, after the BREW SDK is installed, the following MIF

directories and files are created:

BREW\Examples\MIF\Apps\Mono\

RoadWarrior.mifClockApps.mifHelloWorld.mif

...4Grey\


24

BREW SDK Overview

...256Color\


...BREW\Examples\MIF\Usage\

Mono\iimage.mifidialog.mifigraphics.mif

...4Grey\

iimage.mifidialog.mifigraphics.mif

...256Color\

iimage.mifidialog.mifigraphics.mif

...

The default MIF directory is <BREW\Examples\MIF\App\256Color>. You can change the

default by selecting a different directory in the Brew Emulator Settings dialog box (Tools >

Settings).

NOTE: On the target device, the MIF directory is the same as the applet directory. The ability

to have a MIF directory that is different from the applet directory is supported in the SDK on

Windows only. On the device, MIFs must always be present in the same directory as the applet

directory.

Resource directories

The resource directory, a subdirectory under the applet directory, contains system resources

for a particular language type and various color depths. By default, the BREW SDK uses

English. The default resource directory is <BREW\Examples\en>.

Within the <BREW\Examples\en> directory, system resources (and application resources) are

stored for color depths of 1-bit, 2-bit, and 8-bit under the Mono, 4Grey, and 256color

directories.

After the BREW SDK is installed, the following resource directories are created:

BREW\Examples\en\Mono\

AEEControls.barRoadWarrior.bar

...4Grey\

25

BREW SDK Overview


...256Color\


...

NOTE: System resources are saved in AEEControls.bar binary. AEEControls.bri under

<BREW\Examples\en> is the source of the system resource binary. The resource directory

cannot be changed at run time using the Emulator. The resource directory is always searched

within the applet directory.

About paths and filenames

When you are entering paths in BREW SDK applications running on a PC, such as the path

to the initial Applet directory in the Emulator Settings dialog box, you can enter a maximum of

256 characters for the path and filename. However, when you are ready to test your own

BREW applications on an actual device, significantly fewer characters are allowed for the path

and filename. Check with the device OEM for specific path length information.

Case sensitivity is also important when entering paths and filenames. On the PC, you can mix

uppercase and lowercase characters in the same path. On the device, however, all characters

used in paths must be lowercase.

26

BREW Basics

Today’s mobile communications users expect more features from their mobile devices, which

range from very high-end integrated mobile personal digital assistants (PDA) to mass-market

mobile phones that focus on low cost and easy operation. While there has been much

enthusiasm surrounding the possibility of leveraging high-speed ASIC technology to bring new

application functionality even to low-cost devices, the actual task has been complicated by

cost and size factors related to integrating the high-end operating systems seemingly required

to host such applications. Mass-market devices are often characterized by proprietary

solutions that support unique sets of services and interfaces. Although most of these devices

share the same underlying environment, proprietary layers above the ASIC have discouraged

the development of generic applications that can be leveraged across offerings from device

manufacturers.

The BREW solution

QUALCOMM has capitalized on its considerable expertise in the areas of ASICs, mobile

devices, and desktop applications to develop BREW. BREW’s mission is to provide an

efficient, low-cost, extensible, and familiar AEE especially focused on developing applications

that can be seamlessly ported to virtually any handheld device. Unlike the high-end offerings

built on operating systems requiring substantial memory, processor speed, and associated

hardware, BREW runs on the types of devices available today. With BREW, application

developers are able to extend functionality to even the lowest-cost devices.

BREW advantages

Some advantages of BREW’s AEE include the following:

• BREW makes efficient use of both RAM and persistent memory. Objects used by

BREW are loaded and unloaded on an as-needed basis.

• The BREW application environment supports a familiar, event-driven architecture

similar to Microsoft Windows, Macintosh, or UNIX X Windows.

27

BREW Basics

• BREW applets can be localized for different countries.

• All text is managed as Unicode while stored in the most efficient manner supported

for the language selected. BREW also provides support for OEM-specific native

formats for text.

• Developers need not be concerned with low-level platform data structures and

device drivers because all interactions between the application and the device

platform occur through well-defined classes.

• Modules can be developed independently and in parallel, which minimizes

development time and integration challenges.

• Modules can be integrated at the object code level, simplifying the task of adding

modules to the BREW platform.

• BREW supports the receipt of application-directed short message service

messages, such as stock quotes, abbreviated email, or traffic updates.

• BREW provides core classes to interface with the device platform. Device resources

that applets can manage and control with these classes include:

- Shell services

- Time/timers (obtaining current date and time; starting and stopping timers and

alarms)

- Notifications

- Memory management

- File management

- Database management

- Network and sockets

- HTTP

- Download and billing

- User interface controls, including the following:

• Dialogs

• Date controls

• Menu controls

• Text controls

28

BREW Basics

• Time controls

• Static text controls

- Display

- Images (displaying, transformation, animation)

- Graphics

- Sound players (playing MIDI, QCP, and MP3 files)

- Sound (generating ringing, warning sounds, and playing audio files)

- Standard library helper functions

In future releases, core classes will be extended to offer services such as Bluetooth, Global

Positioning System (GPS), and telephony.

The BREW environment

BREW offers application developers a rich, lightweight environment that allows them to

leverage the existing and emerging features provided by QUALCOMM’s mobile station

modem (MSM™) ASIC. BREW’s fully extensible, object-oriented application execution

environment allows development of applets and shared-modules in C or C++. At the same

time, BREW was designed with an eye toward efficiency and RAM conservation on mobile

devices.

BREW supports applications (applets) and shared modules. Applets and modules are

developed as standalone DLLs and are loaded into the Emulator at runtime. Shared modules

include functionality, such as enhanced game APIs that can be used by several applets.

BREW applets and modules are developed in an emulated environment under Windows. To

help you get started, QUALCOMM has provided a number of sample applications, one of

which is presented as a step-by-step tutorial in the BREW Sample Applications section.

29

BREW Basics

BREW exposes a sophisticated set of object technologies that provide the following benefits

to developers:

• Application services supporting a simple, event-based AEE

• Core services to support access to files, network services, memory, and the screen

• Enhanced services such as enhanced graphics capabilities, sound players, and

GPS and voice services

• Integration services, allowing the application developer to leverage services such as

those supported by browsers

The following figure shows how BREW provides a thin layer that supports access to OEM and

ASIC software in support of applets and modules.

Module Module Module

Module Module

Applet Applet Applet Applet Classes

Applet Applet ClassesApplet

OEM(UI, DRIVERS)

MSM (ASIC)Software

Module

Applet

30

BREW Basics

BREW module/interface structure

BREW’s AEE offers a number of distinct categories of services, including several AEE

interfaces such as IShell, IDisplay, and IMenuCtl. Each interface encapsulates a set of

resources and contains methods that allow those resources to be managed. See the BREW

API Reference for a detailed description of the functions within each of these interfaces.

BREW modules can contain one or more applets or classes. Classes are exposed by the

module at runtime and are loaded or unloaded on an as-needed basis.

Using an interface

Interfaces are identified by a 32-bit interface ID. Public interfaces must be reserved via the

QUALCOMM BREW Interface Registry. The Interface Registry does not place any restriction

on the assignment of interface IDs; it is maintained as a service to BREW developers to avoid

interface ID conflicts.

Before using an interface, you must create an instance of it by invoking the CreateInstance()

method of the IShell interface (see note below). A globally unique identifier corresponding to

an interface is passed to the ISHELL_CreateInstance function to retrieve a pointer to the

interface. (Store a pointer to the interface instance within your applet for subsequent use.)

Interfaces are returned by CreateInstance with a positive reference count. Be sure to release

the interface when the applet no longer needs it.

NOTE: For many interfaces, the ISHELL_CreateInstance() method of IShell interface is the

means to create an instance of the interface. However, for certain interfaces, other methods

are used. For example, to create an instance of IImage using a bitmap file, call

ISHELL_LoadImage(). This returns a pointer to the IImage interface.

Becoming an authenticated BREW application developer

Before your application can be tested and approved for distribution, you must provide certain

information that will allow you to become an authenticated BREW application developer. After

you register as an authenticated developer, each of your applications is electronically signed

with your unique identifier, ensuring the integrity of your code. When the code is signed, you

can submit your application to proceed to the application commercialization steps which may

include BREW certification. For more information, see the BREW AppSigner User Guide.

31

BREW Basics

You may apply for authentication at any point in the BREW development process; however,

you cannot obtain ClassIDs for your application until you are authenticated. For more

information, see the BREW MIF Editor Guide, or visit www.qualcomm.com/brew/developer for

more information about the authentication and certification processes.


32

BREW Programming Concepts

This section discusses BREW programming concepts, including applets and modules, BREW

ClassIDs, short message service (SMS) support, TAPI support, shell services, floating point

operations, and the Embedded File System (EFS).

Overview of applets and modules

Each application module in the BREW SDK is developed as a standalone Windows DLL. Each

module can contain one or more applets, and must have a corresponding MIF associated with

it. Created using the BREW MIF Editor, the MIF contains information about the contents of the

module, such as supported classes, supported applets, and applet details (like the title and

icon). The MIF also contains unique ClassIDs for each of the module’s classes, and specifies

which classes are exported for use by other modules. See the BREW MIF Editor Guide for

details on creating new MIFs.

A module can read data from BREW resource files, making strings, images, and dialogs

available to the applications. Storing language- and device-specific data in resource files

makes it possible to create versions of your application for different countries and devices. To

develop resources for applets, use the Resource Editor to generate binary resource files and

corresponding resource header files. See the BREW Resource Editor Guide for details on

creating new resource files.

A BREW applet is developed so that it can be compiled and run on both the Emulator and the

target device. Source and header files that build the foundation of an application are provided

with the SDK. Some files that implement DLL-specific functionality are also provided with the

SDK, allowing you to generate application and resource files. The formats of the resources

and binary resource files used by the application in the BREW environment on the device and

in the Emulator are identical.

33


Following is a list of components required to build an application DLL.

• BREW AEE headers supplied with the BREW SDK

• BREW helper source for simple module creation

• Applet source and headers

• MIF created using the MIF Editor

• Applet resources and resource headers (optional) created using the Resource

Editor

About MIFs

The MIF for the module must be created in the MIF Editor before the applet can be loaded into

the Emulator. Each MIF contains information about the classes and applets supported by a

particular BREW module. The MIF is also required to be shipped as part of the applet bundle.

At system startup on the device or in the Emulator, the Application Manager processes each

MIF to obtain the list of all applications whose information is present within that MIF. Using the

information obtained from the MIF, the Application Manager shows the list of applications

(along with their icons and titles) on the device screen. The information gathered from the MIF

enumeration is stored by BREW for use when classes are requested, and support various

IShell functions, such as those that provide the ability to enumerate the supported applets.

In the sample application called Hello World App, HelloWorld contains a description of the

HelloWorld module. The main information in HelloWorld is summarized as follows:

• Supported classes.

• Supported applets.

• Applet title: Hello World. It appears on the device screen when the applet icon is

selected.

34


BREW ClassIDs

Each class or applet in BREW must have a unique ClassID. The BREW model uses 32-bit IDs

for public classes and applets. These IDs are assigned at the BREW Developer extranet site

www.qualcomm.com/brew/sdk/classid.

NOTE: BREW ClassIDs are available to authenticated developers only. If you are developing

a BREW application and have not yet been authenticated, use dummy IDs until you complete

the authentication process, at which point you need to insert BREW ClassIDs into your

application.

If you are manually assigning ClassIDs to your applets or classes, you must ensure that they

are unique. If two or more classes have the same ID, the class or applet will not run. For

example, consider the following directory structure:

sample/bar.dllsample/foo.mifsample/foo/foo.dll

If bar.mif and foo.mif refer to the same ClassID, the applet will not run because BREW

enumerates the MIFs in the order that they are presented in the directory. For the given

ClassID, BREW first loads bar.mif. So when you try to run the applet, BREW looks for the

directory called bar and cannot find it.

The two types of BREW ClassIDs, interface and applet, are described in the following

subsections.

Interface ClassIDs

Each public BREW interface has an ID that uniquely identifies it. These IDs are reserved and

cannot be used by another interface or applet. When an applet requests an interface pointer

in a call to the CreateInstance function of the shell, it uses this interface ID to identify the

requested interface.

The following interface identifiers are supported in Release 1.0.2 of the BREW AEE.

AEE ClassID Description

AEECLSID_AddrBook Address Book interface identifier

AEECLSID_ARC4 Cipher interface identifier

AEECLSID_BCI BCI interface identifier

http://www.qualcomm.com/brew/sdk/classid

35


AEECLSID_CLOCKCTL Time control interface identifier

AEECLSID_COUNTDOWNCTL Countdown clock control interface identifier

AEECLSID_DATECTL Date control interface identifier

AEECLSID_DATEPICKCTL Date pick control interface identifier

AEECLSID_DBMGR Database manager interface identifier

AEECLSID_DIALOG Dialog box control interface identifier

AEECLSID_DISPLAY Display interface identifier

AEECLSID_FILEMGR File manager interface identifier

AEECLSID_GRAPHICS Graphics interface identifier

AEECLSID_HEAP Heap interface identifier

AEECLSID_HTML HTML Viewer interface identifier

AEECLSID_ICONVIEWCTL Icon View menu control interface identifier

AEECLSID_LICENSE License identifier

AEECLSID_LISTCTL List control interface identifier

AEECLSID_MD5 Hash interface identifier

AEECLSID_MEMASTREAM Memory interface identifier

AEECLSID_MENUCTL Menu control interface identifier

AEECLSID_NATIVEBMP Image interface identifier

AEECLSID_PNG PNG interface identifier

AEECLSID_POSDET PosDet interface identifier

AEECLSID_SOURCEUTIL Source utility identifier

AEECLSID_SOUNDPLAYER SoundPlayer interface identifier

AEECLSID_RINGERMGR Ringer interface identifier

AEECLSID_RSA RSA interface identifier

AEECLSID_SOFTKEYCTL Soft Key menu control identifier

AEECLSID_SHELL IShell identifier

AEECLSID_SOUND Sound interface identifier

AEECLSID_STATIC Static text control interface identifier

AEECLSID_STOPWATCHCTL Stopwatch control interface identifier

AEECLSID_TAPI TAPI interface identifier

AEECLSID_TEXTCTL Text control interface identifier


36


The values these IDs take are predefined in the AEEClassIDs.h header file that comes with

the SDK.

Applet ClassIDs

Each BREW applet that runs on the AEE platform must also have a unique identifier that is

passed to the AEE shell when an applet is loaded. The shell uses this ID to subsequently load

and manage the applet. Accordingly, no two applets can have the same ID.

In the example code shown in BREW Sample Applications on page 54, two local ClassIDs are

defined: AEECLSID_HELLOWORLD and AEECLSID_RESOURCEAPP. These local

definitions are for illustration purposes only. Before submitting your applet for certification, you

must reserve a unique ClassID.

Creating instances

BREW supports applet and module creation through the ISHELL_CreateInstance function,

one of the most powerful APIs supported in BREW. When this function is called, BREW

searches for the specified 32-bit registered ClassID in the list of supported classes. This list

contains entries supported by the core BREW API, and all of the classes and applets added

to the system and detected at system startup through the MIF enumeration process.

Class creation uses the IMODULE_CreateInstance function supported by BREW modules.

However, before this function can be called, the module is loaded into memory and initialized.

BREW loads modules on an as-needed basis only. When a module is loaded, BREW uses its

IModule instance to create the requested class. The module remains loaded until the

reference count of its IModule class goes to 0 (zero), at which time BREW automatically frees

all associated memory for the module.

Typically, BREW calls no functions other than AddRef and Release on a class created using

the ISHELL_CreateInstance function. If an instance of the class is successfully created, an

interface pointer to the instance is returned. When the requestor is finished using the class,

the Release method for the class must be called.

AEECLSID_WEB Web interface identifier

AEECLSID_WEBUTIL Utilities for web applications

AEECLSID_WINBMP Windows Bitmap Viewer interface identifier


37


It is critical that any objects owned by a module increment the reference count of the IModule

when they are created, and decrement the reference count of the IModule when they are

freed. This process allows BREW to unload the module when necessary.

See BREW Sample Applications on page 54 for information about creating instances of

BREW interfaces, including IModule and IApplet.

Creating applets

Under the BREW model, applets are classes that support the functions in the IApplet interface,

allowing BREW to manage all applets using the same simple interface. The IApplet interface

supports only the HandleEvent function in addition to the standard AddRef and Release

methods.

BREW creates applets under two conditions:

• In response to the ISHELL_StartApplet function, which allows applets to be started.

In this case, the applet is created and immediately sent the EVT_APP_START

event. EVT_APP_START informs the applet that it is now active and that it can draw

to the screen.

• In response to registered notifications and alarms. In this case, the applet is created

and immediately receives an event specific to the notification.

Processing applet events

Events are sent to applets through the ISHELL_SendEvent function, either synchronously or

asynchronously. Events sent to applets include keypad, dialog, and control change events.

Here is a sample sequence of events sent to an applet:

EVT_APP_START...Other App Events (EVT_KEY, etc.)...EVT_APP_SUSPEND (optional)EVT_APP_RESUME (optional)...Other App Events (EVT_KEY, etc.)...EVT_APP_STOP

38


Typically, applets only need to process a few events. These can include EVT_APP_START,

EVT_APP_STOP, EVT_KEY, and EVT_COMMAND. If an applet does not process an event,

its HandleEvent method must return FALSE. This allows BREW to do any necessary special

processing for that event.

Suspending and resuming an applet

Under normal conditions in the BREW model, only one active applet can be running at a time.

This does not mean that an applet cannot be instantiated to process notifications, alarms, or

other events. It means that the BREW model generally enforces a single-applet activation

mechanism.

When BREW suspends an applet, it sends the EVT_APP_SUSPEND event to the applet. If

the applet returns TRUE to this event, it indicates to BREW that the applet has processed the

suspend. If the applet does not want to process the Suspend event, it can return FALSE. When

this occurs, BREW stops the applet by sending an EVT_APP_STOP event.

If memory is allocated in the AEEClsCreateInstance() function (that is, when the instance of

the applet is created), it is extremely dangerous to free this memory inside EVT_APP_STOP.

Therefore, any memory allocated inside EVT_APP_START must be cleaned up in

EVT_APP_STOP, and any memory allocated inside AEEClsCreateInstance() must be freed

inside the APPFreeData() function.

In the Emulator, you can simulate the sending of the EVT_APP_SUSPEND event by first

running the applet in the AppManager, and then choosing an option from one of the menus in

the Emulator menu bar (Tools > Settings for example). BREW immediately sends an

EVT_APP_SUSPEND event to the applet. When you click Cancel in the Settings dialog box,

BREW sends the EVT_APP_RESUME event.

In summary, remember the following key points:

• If the applet does not handle suspend, BREW sends EVT_APP_STOP to stop the

applet. Then, instead of resuming the applet, it sends an EVT_APP_START event

to restart the applet.

• If memory is allocated in the AEEClsCreateInstance() function, do not free this

memory inside EVT_APP_STOP.

39


Monitoring incoming SMS messages

The BREW phone layer monitors incoming IS-637 Short Message Service (SMS) messages.

These messages are then conditionally dispatched to applications that meet one or more of

the following conditions:

• The application is registered to receive specific IS-637 messages based upon the

teleservice ID of the message.

• The application is registered to receive all IS-637 CMT-95 (4099) text messages.

• The application is a BREW application to which a CMT-95 text message has been

directed.

The remainder of this subsection describes the format of the application-directed CMT-95 text

messages, as well as the mechanisms used to support their delivery.

Directed SMS messages

BREW’s application-directed SMS mechanism, commonly used to support the transmission of

simple SMS text messages, leverages CMT-95 (teleservice ID 4099) messages. In the case

of BREW, these messages have a special format that allows them to be identified and

dispatched to BREW applications. The format is:

//BREW:<Class ID>:<Text Payload>

Where:

• Class ID is the hex representation of the AEECLSID (BREW AEE ClassID) used

to identify the target application for the message.

• Text Payload is the ASCII text payload of the message. BREW does not interpret

the text payload.

NOTE: If the SMS messages received do not use this format, they cannot launch BREW

applications. They can, however, be viewed using an SMS messaging application.

40


How BREW processes incoming SMS messages

Upon receipt of an SMS message, BREW decodes and analyzes the content of the message

to determine whether it is of interest to BREW. If so, BREW schedules the message for

dispatch/delivery to the target applications.

In the case of an application-directed message, BREW decodes the Class ID to determine the

applicable application. It then passes the message to the application through the

EVT_APP_MESSAGE event. The Text Payload of the message is provided as the argument

to this event notification.

When the application receives the EVT_APP_MESSAGE event, it may or may not be active,

and it does not automatically start. If the application is to be activated as a result of receiving

the message, it can do so using the standard ISHELL_StartApplet API. Also, the application is

not responsible for the memory used to store the message data.

The following sample code illustrates how an incoming application-directed message can be

processed:

static void MyHandler(MyAppType * pme, AEEEvent evt, uint16 wp, uint32 dwp){

switch(evt){

case EVT_APP_START:MyApp_Start(pme);return(TRUE);case EVT_APP_STOP:return(TRUE);case EVT_APP_MESSAGE:{

const char * url = (const char *)dwp;if(url && !STRNICMP(url,”http”,4))ISHELL_BrowseURL(pme->a.m_pIShell, url);

}return(TRUE);}

}

Creating new applications

When you are comfortable with the BREW environment and have looked at the sample

applications, you can create your own new applications. The simplest and quickest way to do

that is with the BREW Application Wizard. The AppWizard guides you through the creation of

all the components required for the successful development of a BREW application. See

BREW Application Wizard add-in on page 125 for details.

41


Language-specific system resources

The BREW environment uses a set of system resource files that are required for successful

operation of BREW. These resource files are specific to the languages supported by the

device. For example, the IDateCtl and ITimeCtl interfaces use a resource file called

AEEControls.bar, which contains definitions of all resources used by these interfaces.

In the device environment, all language-specific resource files are placed in a directory specific

to that language. The name of the directory assigned to each language is derived from the ISO

639 code for that language. For example, the ISO 639 code for the English language is the

string “en.” All system resources specific to English must be placed inside a directory called

en, which must be placed within the applet directory. Therefore, if the applet directory is set to

<BREW\apps>, the English-specific resource files must be placed in the directory

<BREW\apps\en>.

The concept explained above is also supported in the SDK, so be sure to place the BREW

system resources in the language-specific directory. The BREW SDK installation ensures that

this is done when BREW is installed. This mechanism continues to work as long as you do not

change the applet directory. If, however, you change the applet directory to another directory

(for example, <C:\MyApps>), you must do the following to ensure that BREW works

successfully:

1. Create a language-specific subdirectory within the application directory. For

example, create the directory <C:\MyApps\en>.

2. Copy the entire contents of the en subdirectory from the BREW installation

location, <C:\ProgramFiles\Brew\examples\en>, to the directory <C:\MyApps\en>.

Repeat these steps whenever you change the applet directory to a different location. If you do

not follow these steps, BREW interfaces will not be able to find the required resource files and

some of the interfaces, such as IDateCtl and ITimeCtl, may not function properly.

Floating-point operations

The BREW platform does not support floating-point operations. If you write an application with

a floating-point operation and test it in the BREW SDK, it works as expected because the

underlying platform is the Windows operating system. However, floating-point operations are

not supported on the device platform and must not be used in BREW applications.

42


Building BREW applications for wireless handsets

To build your applications for wireless handsets with the QUALCOMM Mobile Station Modem

(MSM) chipset, you have the choice of any of the following ARM Development Suites: 1.0.1,

1.1, or BREW Builder™.

ARM Development Suite 1.0.1

The BREW SDK is shipped with makefiles for each sample application. These makefiles are

compliant with ADS 1.0.1. The makefile for the HelloWorld application, helloworld.mak, is

shown below.

#===================================================================# Name:# helloworld.MAK## Description:# Makefile to build the helloworld downloadable module.## The following nmake targets are available in this makefile:## all - make .elf and .mod image files (default)# clean - delete object directory and image files# filename.o - make object file## The above targets can be made with the following command:## nmake /f helloworld.mak [target]## Assumptions:# 1. The ARM ADS 1.0.1 tools are installed in the c:\ads directory.# 2. This Makefile can be used with the ARM ADS 1.0.1 Compiler only. ## Notes:# 1. While building the application using this make file, the # following warnings may be # received. They can be safely ignored:# "Warning: C2067I: option -zas will not be supported in future # releases of the compiler# "Warning: C2071W: option -za will not be supported in future # releases of the compiler # "Warning: L6305W: Image does not have an entry point. (Not # specified or not set due to # multiple choices).# ## Copyright © 2000-2001 QUALCOMM Incorporated.# All Rights Reserved.# QUALCOMM Proprietary/GTDR##-------------------------------------------------------------------#===================================================================

#-------------------------------------------------------------------# Target file name and type definitions#-------------------------------------------------------------------

43


SUPPORT_DIR = ..\..\srcSUPPORT_INCDIR = ..\..\incSUPPORT_APPIDDIR = ..

TARGET = helloworld # Target name for output files and object dirEXETYPE = elf # Target image file formatMODULE = mod # Downloadable module extensionMAKE_TARGET= helloworld # Target Makefile name

#-------------------------------------------------------------------# Target compile time symbol definitions#-------------------------------------------------------------------

DYNAPP = -DDYNAMIC_APP

#-------------------------------------------------------------------# Software tool and environment definitions#-------------------------------------------------------------------

ARMBIN = c:\ads\bin # ARM ADS application directoryARMINC = c:\ads\include # ARM ADS include file directoryARMLIB = c:\ads\lib # ARM ADS library directory

ARMCC = $(ARMBIN)\armcc # ARM ADS ARM 32-bit inst. set ANSI C compilerLD = $(ARMBIN)\armlink # ARM ADS linkerHEXTOOL = $(ARMBIN)\fromelf # ARM ADS utility to create hex file from image

OBJ_CMD = -o # Command line option to specify output filename

#-------------------------------------------------------------------# Processor architecture options#-------------------------------------------------------------------

CPU = -cpu ARM7TDMI # ARM7TDMI target processor

#-------------------------------------------------------------------# ARM Procedure Call Standard (APCS) options#-------------------------------------------------------------------

ROPI = ropi # Read-Only(code) Position independenceINTERWRK = interwork # Allow ARM-Thumb interworking

APCS = -apcs /$(ROPI)/$(INTERWRK)

#-------------------------------------------------------------------# Additional compile time error checking options#-------------------------------------------------------------------

CHK = -fa # Check for data flow anomolies

#-------------------------------------------------------------------# Compiler output options#-------------------------------------------------------------------

OUT = -c # Object file output only

#-------------------------------------------------------------------# Compiler/assembler debug options

44


#-------------------------------------------------------------------

DBG = -g # Enable debug

#-------------------------------------------------------------------# Compiler optimization options#-------------------------------------------------------------------

OPT = -Ospace -O2 # Full compiler optimization for space

#-------------------------------------------------------------------# Compiler code generation options#-------------------------------------------------------------------

END = -littleend # Compile for little endian memory architectureZA = -za1 # LDR may only access 32-bit aligned addressesZAS = -zas4 # Min byte alignment for structures

CODE = $(END) $(ZA) $(ZAS)

#-------------------------------------------------------------------# Include file search path options#-------------------------------------------------------------------

INC = -I. -I$(SUPPORT_INCDIR) -I$(SUPPORT_APPIDDIR)

#-------------------------------------------------------------------# Compiler pragma emulation options#-------------------------------------------------------------------

#-------------------------------------------------------------------# Linker options#-------------------------------------------------------------------

LINK_CMD = -o #Command line option to specify output file #on linking

ROPILINK = -ropi #Link image as Read-Only Position Independent

LINK_ORDER = -first AEEMod_Load

#-------------------------------------------------------------------# HEXTOOL options#-------------------------------------------------------------------

BINFORMAT = -bin

#-------------------------------------------------------------------# Compiler flag definitions#-------------------------------------------------------------------

CFLAGS0 = $(OUT) $(DYNAPP) $(INC) $(CPU) $(APCS) $(CODE) $(CHK) $(DBG)CFLAGS = $(CFLAGS0) $(OPT)

#-------------------------------------------------------------------# Linker flag definitions

45


#-------------------------------------------------------------------

LFLAGS = $(ROPILINK)

#-------------------------------------------------------------------# Default target#-------------------------------------------------------------------

all : $(TARGET).$(MODULE)

#-------------------------------------------------------------------# Clean target#-------------------------------------------------------------------

# The object subdirectory, target image file, and target hex file are deleted.

clean : @echo ------------------------------------------------------ @echo CLEAN -del /f AEEAppGen.o -del /f AEEModGen.o -del /f $(TARGET).o -del /f $(TARGET).$(EXETYPE) -del /f $(TARGET).$(MODULE) @echo ------------------------------------------------------

#===================================================================# DEFAULT SUFFIX RULES#===================================================================

# The following are the default suffix rules used to compile all objects # that are not specifically included in one of the module specific rules # defined in the next section.

# The following macros are used to specify the output object file, MSG_FILE# symbol definition and input source file on the compile line in the rules# defined below.

SRC_FILE = $(@F:.o=.c) # Input source file specificationOBJ_FILE = $(OBJ_CMD) $(@F) # Output object file specification

.SUFFIXES :

.SUFFIXES : .o .dep .c

#-------------------------------------------------------------------# C code inference rules#-------------------------------------------------------------------

.c.o: @echo ------------------------------------------------------ @echo OBJECT $(@F) $(ARMCC) $(CFLAGS) $(INC) $(OBJ_FILE) $(SRC_FILE) @echo ------------------------------------------------------

{$(SUPPORT_DIR)}.c.o: @echo ------------------------------------------------------ @echo OBJECT $(@F) $(ARMCC) $(CFLAGS) $(INC) $(OBJ_FILE) $(SUPPORT_DIR)\$(SRC_FILE) @echo ------------------------------------------------------

46


#===================================================================# MODULE SPECIFIC RULES#===================================================================

APP_OBJS = AEEAppGen.o \ AEEModGen.o \ $(TARGET).o

#-------------------------------------------------------------------# Lib file targets#-------------------------------------------------------------------

$(TARGET).$(MODULE) : $(TARGET).$(EXETYPE) @echo ------------------------------------------------------ @echo TARGET $@ $(HEXTOOL) $(TARGET).$(EXETYPE) $(BINFORMAT) $(TARGET).$(MODULE)

$(TARGET).$(EXETYPE) : $(APP_OBJS) @echo ------------------------------------------------------ @echo TARGET $@ $(LD) $(LINK_CMD) $(TARGET).$(EXETYPE) $(LFLAGS) $(APP_OBJS) $(LINK_ORDER)

# ------------------------------# DO NOT EDIT BELOW THIS LINE

AEEAppGen.o : $(SUPPORT_DIR)\AEEAppGen.cAEEAppGen.o : $(SUPPORT_INCDIR)\AEEAppGen.h

AEEModGen.o : $(SUPPORT_DIR)\AEEModGen.cAEEModGen.o : $(SUPPORT_INCDIR)\AEEModGen.h

$(TARGET).o : $(TARGET).c#$(TARGET).o : $(TARGET).h$(TARGET).o : $(SUPPORT_INCDIR)\AEEAppGen.h$(TARGET).o : $(SUPPORT_INCDIR)\AEEModGen.h

ARM Development Suite 1.1

To build BREW applications for ARM Development Suite 1.1, you need to convert the ARM

Development Suite 1.0.1 makefile for ARM Development Suite 1.1.

NOTE: The minimum requirements for the conversion are build 717 or higher of the ADS 1.1

compiler.

To convert an ARM 1.0.1 makefile for ARM 1.1

1. Open the ARM Development Suite 1.0.1 makefile.

2. Change the following line:

ZA = -za1 # LDR may only access 32-bit aligned addresses

47


To

ZA = -zo # LDR may only access 32-bit aligned addresses

3. Save the file.

ARM BREW Builder

QUALCOMM has teamed with ARM to provide developers with components that are:

• Compatible with binary software objects delivered through BREW.

• Highly optimized binaries (best-in-class performance and code density).

• Commercially affordable. The cost of ARM BREW Builder is approximately one-third

the cost of regular ARM Development Suite 1.1.

The ARM BREW Builder includes the Compiler, Linker, and Assembler components of the

ARM Developer Suite. The BREW Code Generation Tools (CGT) package is available to

authenticated BREW developers for $1,500. A free, 45-day evaluation unit of the full ARM

compiler is also available at http://www.arm.com.

To purchase the BREW Code Generation Tools, or for more details, please visit the BREW

web site at http://www.qualcomm.com/brew/developer.

ARM BREW Builder makefiles are the same as those produced with ARM Development

Suite 1.1.

Comparing ARM BREW Builder and ARM Development Suite 1.1

The following are the differences between ARM BREW Builder and ARM Development

Suite 1.1. The ARM BREW Builder:

• does not include the CodeWarrior IDE.

• cannot create or update libraries (although it can use libraries).

• does not support all floating-point varieties.

• includes only .PDF documentation, and does not include ARM's DynaText tool.


http://www.arm.com

48


NOTE: The fact that the ARM BREW Builder cannot create libraries is not a limitation because

BREW application developers are not supposed to write static applications, but BREW

extensions, which can be built with the ARM BREW Builder.

Accessing shell services

Modules and applets gain access to all external services using interfaces retrieved from the

root IShell interface. This module interface is passed to the load function and initialized for

functions of the module. Using the IShell interface, applets and modules can request pointers

to all of the other interfaces they require. Each interface has an ID that uniquely identifies the

given interface. The IShell_CreateInstance() function is called with the unique interface

ClassID to retrieve a pointer to that interface.

IShell interface

The IShell interface provides a number of services to applets for accessing device operating

system functionality. Major IShell features allow you to:

• Obtain additional classes supported by the shell or underlying drivers

• Obtain information about device capabilities

• Activate and deactivate the current applet

• Manage timers

• Access system time and time conversion routines

• Manage dialog boxes to retrieve user input

• Load resources used by applets

• Pass events to different interfaces

• Show message boxes

• Post alarms

• Register and query for protocol and content viewers

See the BREW API Reference for detailed descriptions of IShell’s features.

49


IBase interface

The IBase interface class defines the base structure incorporated into all AEE class objects.

Each AEE interface class/structure contains the IBase functions as the first two interfaces

defined in the public class definition.

Since AEE objects can be dynamically allocated, a mechanism must be used independently

of the specific memory manager to free or release the objects. The IBase interface provides

two basic functions: AddRef and Release, which allow you to:

• Dynamically allocate interface objects

• Free or release interface objects

All BREW classes must implement the functions in the IBase interface.

IModule and IApplet interfaces

IModule and IApplet are fundamentally different from all other interfaces in that they implement

services provided by an application, as opposed to services used by an application. They

provide a mechanism to the shell for loading, managing, and passing events to an application.

The BREW SDK provides you with a default implementation of the IModule and IApplet

interfaces.

IModule interfaces

The basis for the BREW model is a mechanism whereby the module (IModule) is linked to or

loaded by the core device shell (IShell). These modules export a single defined entry point that

is called to retrieve the interface known as the IModule. The IModule provides only two

functions. The first and most critical function allows BREW to request a specific class instance

from the module. The second function allows BREW to request that the module free any

unwanted system resources.

BREW supports both static and dynamic modules. Static modules are built into the device by

the manufacturers; therefore, only device manufacturers can develop static modules. Dynamic

modules can be downloaded and run on the device. The SDK supports dynamic modules only.

50


Both static and dynamic modules export a single entry point, which is the very first function to

be called or run in the module. In the case of statically linked modules, this entry point serves

to retrieve a list of supported classes and applets. The entry point also returns a pointer to the

module’s main Load function. BREW calls the Load function to ask the module to create

classes supported by the module. The entry point must have a unique name, which allows the

entry point to be added to a static module table managed by the device integrator.

Dynamically loaded modules only export the Load function. This is accomplished by placing it

as the first function in the first object linked to the relocatable code image for the module. The

module can be loaded by BREW on an as-needed basis. Although not discussed in detail in

this document, digital signing of applications is required for them to be loaded dynamically onto

target devices.

IApplet interface

The IApplet interface implements services provided by an applet. The main service of the

IApplet interface is providing a mechanism to the shell to pass events to an applet.

Events passed to an applet

The BREW application model is based on an event-driven engine. After an applet is loaded, it

receives all input through events, which are received by the HandleEvent function of the

applet. Since it is an event-driven environment, BREW demands that events be handled in a

timely manner. This means that an applet is expected to quickly handle the event and return.

Under BREW, substantial delays in processing events may result in the applet being shut

down to safeguard the device.

When BREW passes an event to an applet, the applet indicates whether it handled the event

by returning TRUE (handled) or FALSE (not handled). When an applet must pass the event to

other event handlers (such as controls), it can simply return the result of that call.

Applets receive three event-related inputs, which are passed in the second, third, and fourth

parameters of the HandleEvent function. Below is an example signature of the event handler

function.

boolean HandleEvent(IApplet * pIApp, AEEEvent eCode, uint16 wParam, uint32 dwParam)

51


The second parameter is of type AEEEvent, and it specifies the main event received by the

applet. Examples of events that the applets receive are Start, Stop, Suspend, Resume, and

Alarm. A detailed list of events that an applet can receive is provided in Appendix B: Event

Codes and Key Codes.

The third and fourth parameters are the short data and long data corresponding to the event

received. These values are context-specific and are defined in accordance with the definition

of the event.

• Some events contain event-specific data in both the short data and long data fields.

Examples of such events are EVT_KEY_UP, EVT_DEY_DOWN,

EVT_DIALOG_START, EVT_COMMAND, and EVT_CTL_SET_TITLE.

• Some events contain data in either the short data field or the long data field only. An

example of an event that has data in only the short data field is EVT_ALARM.

Examples of events that have data only in the long data field are

EVT_NET_STATUS and EVT_CTL_CHANGING.

• Some events contain no data in either the short or long data fields. Examples of such

events are EVT_START, EVT_STOP, EVT_SUSPEND, and EVT_RESUME.

The event table in Appendix A gives more details on which event is accompanied with which

data field, and what each field contains.

Tips for event handling

When implementing an applet, consider and handle only those events that your applet might

want to process. Typically, you can ignore many events. For example, if the applet implements

a game that uses only the up, down, left, and right arrow keys as input, and an event

corresponding to a keypress of keys 0-9 is received, it can be ignored.

Some events are not sent to the applet unless it specifically indicates that it wants such

notifications. Critical events received by the applet cannot be ignored, regardless of the state

of the applet. EVT_STOP and EVT_SUSPEND are examples of critical events that impact the

applet in any state. Be careful when receiving all the critical events in any given state of the

applet. You may have to save data/context in processing a received event.

Keypress events are sent to the applet as EVT_KEY events. The short data field contains the

primary key code. The long data field values are OEM specific. The key codes passed to an

applet are in Unicode values. The values of key codes and their symbols are defined in

Appendix B: Event Codes and Key Codes.

52


For example, if key 2 is pressed, the short data field contains the Unicode value corresponding

to key symbol 2. This feature allows you to handle a key press in the context of an applet.

Using the Configurator, you can alter which of the primary key codes is passed to an applet.

The device OEM determines the primary key code on the target device.

When a key is pressed or released, ISHELL sends asynchronous events to the active applet.

Following is a list of key events an applet can receive, and a brief description of each key

event.

BREW key event dwParam structure

For the EVT_KEY_PRESS, EVT_KEY_RELEASE, and EVT_KEY events, dwParam contains

OEM-specific values.

EVT_KEY_PRESS Received by an applet when a key is pressed. Parameters include the following:

• wParam: primary code

• dwParam: OEM-specific

EVT_KEY_RELEASE Received by an applet when a key is released. Parameters include the following:



EVT_KEY Sent either when a key is pressed or when a key is released, or both, depending on the device manufacturer’s choice. Applications are expected to do the key handling when this event is received.

Because each handset ships with a particular key handling setting, you must write your applications within this specification. The Configurator supports an attribute called Key Action, which can be set to one of the following:

• DOWN: the event is sent when a key is pressed. This is default behavior.

• UP: the event is sent when a key is released.

• UPDOWN: the event is sent when a key is pressed and when it is released; that is, two EVT_KEY events are sent.

Parameters include the following:



NOTE: For a particular device, primary code, key action, and key symbols are configured for each key in the Configurator.

53


Embedded File System

The device contains an Embedded File System (EFS). There are several differences in the

behavior of the EFS versus a file system on a desktop (for example, Windows NT).

Applications must adhere to the following guidelines while trying to access files or APIs that

involve the file system (Databases, SoundPlayer, and so forth).

• When specifying the path for a file, do not include the drive letter. For example, the

following call is invalid:

IFILEMGR_OpenFile(pIFileMgr, "C:\\Test.dat",_OFM_CREATE);

There is no concept of drives on the EFS; therefore, they are not supported on the

Emulator.

• When specifying the path for a file, the paths “.\” and “..\” are not supported. For

example, the following calls are invalid:

IFILEMGR_OpenFile(pIFileMgr, ".\\Test.dat",_OFM_CREATE);

IFILEMGR_OpenFile(pIFileMgr, "..\\Test.dat",_OFM_CREATE);

• A filename cannot contain two periods (dots) within it. For example, the name

test.log.dat is invalid.

• When a filename is specified, BREW always tries to open that file in the directory of

the current module. For each module, the directory in which that module exists acts

as the root. Accordingly, when a file path is specified as <test\foo.dat>, the test

directory is searched within the directory of the module that has made this API call.

• The call to IFILEMGR_OpenFile() creates the intermediate directories if they do not

exist and if the file open mode is specified as: _OFM_CREATE. For example:

IFILEMGR_OpenFile(pIFileMgr, "Test1\\Test2\\Test.dat",_OFM_CREATE);

This call creates the subdirectories Test1\Test2, and then creates the file Test.dat

within Test2. These subdirectories and file are created within the applet's directory.

You will see similar behavior when dealing with databases because BREW

databases are stored in BREW files, and the name of the database is simply the

name of its file.

54

BREW Sample Applications

This BREW SDK includes an Examples directory with a wide variety of sample applications

you can use to learn to write BREW applications, or as the basis for creating your own

applications. Application source code for a few of the applications are shown in this section.

Reading the line-by-line explanations of these sample applications can help prepare you for

creating your own applications.

NOTE: Although the sample applications included in the BREW SDK have been thoroughly

tested, it is important that you employ reasonable user interface design and usability principles

in the creation of your own applications.

The sample applications included with the BREW SDK are of two types, demonstration and

usage.

• Demonstration applications demonstrate the capabilities of the components of

BREW. They are intended to act as references and starting points for developing

new applications. See Sample demonstration applications below for a list of the

demo applications included with the BREW SDK.

• Usage applications demonstrate how to use BREW interfaces and APIs. In most

cases, the application file names begin with an "I," such as IMenuCtl. See Sample

usage applications on page 59 for a list of the usage applications included with the

BREW SDK.

The sample applications can be run and viewed on the Emulator. See Running sample

applications on page 105 for details.

NOTE: The sample source code provided with the BREW SDK has been written to

demonstrate the usage of BREW data structures and functions. Despite the extensive testing

that each sample application undergoes in our test labs, the source code was not intended to

pass the rigid requirements of TRUE BREW Certification because many of the sample

applications are not fully-featured. A notable exception is Road Warrior, version 1.1. This is a

TRUE BREW tested application. The source code and instructions are included in the BREW

SDK 1.1 release.

55


Sample demonstration applications

The following table describes the sample demonstration applications, the interfaces used by

each, and the files you need to download to the handset to run the sample applications.

NOTE: The Test Signature (SIG) file listed in the last column, obtained from the BREW

Developers Extranet, enables your application to run on a particular handset. For more

information, see the BREW Developers Extranet web site.

Application Interfacesused

Description and usage Files needed to run application on handset

Address Book IAddrBookIAddrRecIAppletIDisplayIMenuCtlIModuleIShell

A simple address book application.

This sample application demonstrates:

• Usage of the IAddrBook and IAddrRec interfaces in BREW.

addrbook.mifaddrbook.modaddrbook.sig

Calender/Scheduler

IDatabaseIDateCtlIDBMgrIDisplayIMenuCtlIShellITextCtlITimeCtl

A simple personal assistant application.


• Basic concepts of BREW personal assistant-like applications.

• Usage of Database Manager (IDBMgr) and Databases (IDatabase) interfaces.

• Usage of BREW UI controls: Menu (IMenuCtl), Text (ITextCtl), Date (IDateCtl), and Time (ITimeCtl).

calapp.barcalapp.mifcalapp.modcalapp.sig

Calculator and Tip Calculator

IDisplayIMenuCtlIModuleIShell

A simple calculator and a handy tip calculator.


• Basic calculator and computation functionality in BREW.

• Floating point arithmetic in BREW.

• Use of Soft-Key menu control and display using BREW fonts.

calcapp.barcalcapp.mifcalcapp.modcalcapp.sig

56


Clock applications

• alarm clock

• countdown

• stopwatch

IAppletIDisplayIMenuCtlIModuleIShellITimeCtl

Various time-related applications.


• Usage of the ITimeCtl interface to implement various time-related functions.

clockapps.barclockapps.mifclockapps.modclockapps.sig

DisplaySpeed Tune

IDisplayIFileMgrIGraphicsIMenuCtlIShellISoundIStatic

Application that benchmarks display and file operations. This application is used for device speed emulation in Emulator. See Configuring devices for speed emulation on page 112 for details.


• Basic benchmarking mechanism in BREW.

• Cooperative multi-tasking (yielding) during benchmarking.

• Floating point arithmetic in BREW.

• BREW Directory and File operations using IFileMgr and IFile.

dispspeedtune.bardispeedtune.mifdispspeedtune.moddispspeedtune.sigtestfile.rd

Hello World IAppletIDisplayIModuleIShell

A very simple (probably your first) BREW application that shows Hello World on the device screen.


• BREW application structure, including fundamental BREW interfaces: IShell, IDisplay, IModule, and IApplet.

• How to define and show a string using the IDisplay interface.

• Minimum components required to build a BREW application.

helloworld.mifhelloworld.modhelloworld.sig



57


Keypad IAppletIDisplayIHeapIModuleIShell

When a device key is pressed, KeyPad shows the primary key code associated with the device key.


• Handling of the EVT_KEY key event, including processing of primary key code (contained in wParam).

keypad.barkeypad.mifkeypad.modkeypad.sig

Memo IDatabaseIDBMgrIDBRecordIDisplayIMenuCtlIModuleIShellITextCtl

A basic memo pad application.


• Memo pad implementation using ITextCtl for text input and editing.

• Persistence of memos using IDBMgr, IDatabase, and IDBRecord.

• Soft-Key menu control and its association with ITextCtl.

memoapp.barmemoapp.mifmemoapp.modmemoapp.sig

MIDI IAppletIDisplayIFileIFileMgrIMenuCtlIModuleIShellISoundPlayer

An audio player that plays MIDI, MP3, and QCP (PureVoice) formats.


• Player application implementation using the ISoundPlayer interface.

• Controlling playback of an audio file.

• Player UI implementation using Soft-Key menu control containing images.

• Listing of audio files using IFileMgr and selection using IFile.

midiplayer.barmidi.mifmidi.modmidi.sig

Look for music files under <BREW\examples\midi\music>



58


Road Warrior IAppletIDisplayIFileIFileMgrIMenuCtlINetMgrIShellIWebIWebResp

A TRUE BREW tested application that connects to the California Department Of Transportation web-server and shows real-time traffic data for major San Diego highways. The web-server URL and highways are configurable.


• How to use INetMgr and ISocket to connect to a web-server via the Internet.

• How to retrieve and parse data using AEEStdLib functions.

• Reading of a configuration file containing URL and highway names using IFileMgr and IFile.

• Display of data using IMenuCtl.

roadwarrior.mifroadwarrior.modroadwarrior.sig

Security IAppletICipherIDisplayIHashIMenuCtlIModuleIRSAIShell

A basic security services application.


• Usage of the IHash, IRSA, and ICipher interfaces.

NOTE: The IHash interface currently supports only the MD5 hashing algorithm.

security.mifsecurity.modsecurity.sig

Socket IAppletIDisplayIModuleINetMgrIShell

A basic net access application. It connects to a URL and retrieves data.


• Usage of INetMgr and ISocket.

socket.mifsocket.modsocket.sig

Sound IAppletIDisplayIMenuCtlIModuleIShellISound

A basic sound services application.


• How to use the BREW ISound interface for basic audio services.

• How to play a predefined BREW tone and list of tones.

• How to vibrate the device.

• Usage of ISHELL_Beep() with all beep types.

sound.mifsound.modsound.sig



59


NOTE: For details on the interfaces, see the BREW API Reference.

Sample usage applications

The following table describes the sample usage applications, the interfaces used by each, and

situations where you might want to refer to the sample applications. The usage applications

included with the BREW SDK demonstrate how to use BREW interfaces and APIs; however,

they do not represent examples of TRUE BREW tested code.

NOTE: The Test Signature (SIG) file listed in the last column, obtained from the BREW

Developers Extranet, enables your application to run on a particular handset. For more

information, see the BREW Developers Extranet web site.

Webber IAppletIDateCtlIDisplayIGraphicIHeapIModuleIPeekIShellISourceISourceUtilITimeCtlIWebIWebResp

An IWeb usage application that accesses a URL and fetches data.


• Usage of the BREW IWeb and IWebResp interfaces. The IWeb Interface is the context in which web transactions are conducted and completed. IWeb is the API for dealing with BREW's web support. An IWeb interface pointer is designed to be created at application startup, initialized, and used until application shutdown. IWeb's most interesting entry point is IWEB_GetResponse(), which takes a URL and an AEECallback and kicks off an asynchronous web transaction. IWeb supervises proxying, connection Keep-Alives, and other optional web-related behaviors.

• Usage of the IPeek, ISource, and ISourceUtil interfaces.

webber.mifwebber.modwebber.sig



60




C++ Application IAppletIDisplayIMenuCtlIModuleIShellIStatic

A BREW application written using C++.


• How to take advantage of C++ in writing BREW applications.

• How to interface with C-based BREW from a C++ BREW application.

cppapp.mifcppapp.modcppapp.sig

Extension Class Application

IDisplayIModuleIShell

The BREW Extension Module. The sample application uses the Exported Class in the Extension Module.


• The BREW Extension Module (ExtMod).

• How to write an ExtMod that contains one or more exported Classes.

• A sample MIFfor the ExtMod.

• A BREW application using ExtMod.

• How to create an instance of an exported Class in the Extension application, and how to use that Class.

• A sample MIF for the application that shows dependency on an exported Class in the Extension application.

extension.mifextension.modextension.sig

Extension Usage Application

IAppletIDisplayIExtensionClsIModuleIShell

This applet is used to invoke the Extension Class application.


• Loading a dynamic class module and calling functions from it.

extuse.mifextuse.modextuse.sig

61


I411 Viewer I411 ViewerIAppletIAStreamIDisplayIImageIMenuCtlIShell

A viewer application that implements a new Viewer interface which overrides the BREW IImage interface.


• Creation and implementation of the new Viewer interface that overrides the corresponding BREW interface.

• Registering and de-registering of the Viewer interface with the BREW Shell Registry using ISHELL_RegisterHandler().

• Using the new interface functionality.

b.411I411Viewer.barI411Viewer.mifI411Viewer.modI411Viewer.sig

IDateCtl IAppletIDateCtlIDisplayIMenuCtlIModuleIShell

Allows the user to create and operate on IDateCtl objects that are used to invoke Calender date related functionality.


• Usage of the IDateCtl interface.

idatectl.baridatectl.mifidatectlusage.modidatectlusage.sig

IDBUsage IAppletIDatabaseIDBMgrIDBRecordIDisplayIMenuCtlIModuleIShell

Allows the user to create and operate on Database objects.


• Usage of the IDBMgr, IDatabase, and IDBRecord interfaces.

idbusage.baridbusage.mifidbusage.modidbusage.sig

IDialog IAppletIDateCtlIDialogIDisplayIMenuCtlIModuleIShell

Allows the user to create and manage user interface dialogs.


• Usage of the IDialog interface.

dialog.baridialog.mifidialogusage.modidialogusage.sig



62


IDisplay IAppletIDisplayIMenuCtlIModuleIShell

Allows the user to create and operate on IDisplay interface. IDisplay interface offers basic display services.


• Usage of the IDisplay interface.

idisplay.baridisplay.mifidisplayusage.modidisplayusage.sig

IFile IAppletIDisplayIFileIFileMgrIMenuCtlIModuleIShell

IFile interface functions consist of operations performed on files opened by the IFileMgr interface.


• Usage of the IFile and IFileMgr interfaces.

ifile.barifile.mififileusage.modifileusage.sig

IGraphics IAppletIDisplayIGraphicsIMenuCtlIModuleIShell

Allows the user to create and operate on IGraphics objects. IGraphics objects are used to invoke graphics-related functionality.


• Usage of the IGraphics interface.

igraphics.barigraphics.mifigraphicsusage.modigraphicsusage.sig

IHeap IAppletIDisplayIHeapIMenuCtlIModuleIShell

Functions allocate and free blocks of memory and return information about the amount of memory available and in use in the device.


• Usage of the IHeap interface.

iheap.mifiheapusage.modiheapusage.sig

IHTMLViewer IAppletIDisplayIFileMgrIHtmlViewerIModuleIShell

Allows the user to specify a URL and load and view an HTML file on the device.


• Usage of the IHtmlViewer interface.

ihtmlviewer.mifihtmlviewer.modihtmlviewer.sig



63


IImage IAppletIDisplayIFileIFileMgrIImageIMenuCtlIModuleIShell

Allows the user to display images.


• Usage of the IImage interface.

iimage.bariimage.mifiimageusage.modiimageusage.sigsample.bmp

ILicense IAppletIDisplayILicenseIMenuCtlIModuleIShell

Allows the user to control application usage.


• Usage of the ILicense interface.

ilicense.mifilicense_10days.mifilicense_10min.mifilicense_7use.mifilicense_dec31.mifilicense_expired.mifilicense_unlimit.mifilicense.modilicense.sig

IMemStream IAppletIDisplayIFileIFileMgrIMemAStreamIMemStreamIModuleIShell

Allows the user to create and operate on IMemStream objects.


• Usage of the IMemStream interface.

imemstream.barimemstream.mifimemstream.modimemstream.sigbrowsericon.bmp

IMenuCtl IAppletIDisplayIMenuCtlIModuleIShell

Used to create various types of menus from which device users can make selections.


• Usage of the IMenuCtl interface.

imenuctl.barimenuctl.mifimenuctlusage.modimenuctlusage.sig

INetSocket IAppletIDisplayIModuleIMenuCtlINetMgrINetSocketIShellISocket

Allows the user to create and operate on INetMgr and ISocket interface objects. INetMgr and ISocket objects are used to invoke network connectivity-related functionality.


• Usage of the INetSocket interface.

inetsocket.mifinetsocketusage.modinetsocketusage.sig



64


INotify IAppletIDisplayIMenuCtlIModuleINotifyIShell

Implements services that allows a user applet to register with the shell to be notified when a particular event has occurred


• Usage of the INotify interface.

inotify.mifinotifyusage.modinotifyusage.sig

IRinger IAppletIAStreamIDisplayIFileIFileMgrIMemAStreamIMemStreamIMenuCtlIModuleIRingerIRingerMgrIShell

Allows the user to create and operate on IRingerMgr objects. The IRingerMgr interface offers basic ringer services.


• Usage of the IRinger interface.

iringer.bariringer.mifiringer.modiringer.sigAEE_TONE_0.wavAEE_TONE_1.wav

IShell IAppletIDisplayIMenuCtlIModuleIShell

Allows the user to create and operate on the IShell object. IShell objects are used to invoke system level functionality.


• Usage of the IShell interface.

ishellusage.barishell.mifishellusage.modishellusage.sig

ISound IAppletIDisplayIMenuCtlIModuleIShellISound

Allows the user to create and operate on the ISound object. The ISound interface offers basic sound services.


• Usage of the ISound interface.

isound.mifisoundusage.modisoundusage.sig



65


ISoundPlayer IAppletIDisplayIFileIFileMgrIMenuCtlIModuleIShellISoundISoundPlayer

Allows the user to create and operate on ISoundPlayer objects. ISoundPlayer interface offers services that play and operate on MP3 and MIDI sound files.


• Usage of the ISoundPlayer interface.

isoundplayer.mifisoundplayer.modisoundplayer.sig

Look for music files under <BREW\examples\midi\music>

IStatic IAppletIDisplayIImageIMenuCtlIModuleIShellIStatic

Allows the user to display static text controls, consisting of a text message and title.


• Usage of the IStatic interface.

static.baristatic.mifistaticusage.modistaticusage.sig

ITAPI IAppletIDisplayIFileIFileMgrIMenuCtlIModuleIShellITAPI

A simple interface to the telephony layer in the device. This function provides the following services:

• Retrieving status.

• Placing voice calls.

• Extracting SMS text from SMS messages.

• Obtaining caller ID on incoming or in-progress calls.


• Usage of the ITAPI interface.

itapi.mifitapiusage.moditapiusage.sig

ITextCtl IAppletIDisplayIMenuCtlIModuleIShellITextCtl

Allows the user to create and operate on ITextCtl objects. ITextCtl objects are used for basic text entry-related services.


• Usage of the ITextCtl interface.

itextctl.baritextctl.mifitextctlusage.moditextctlusage.sig



66


NOTE: For details on the interfaces, see the BREW API Reference.

Sample 1: "Hello World"

This subsection introduces a simple application that prints Hello World on the device screen.

When this application is run, it clears the screen and displays the text string Hello World, as

shown in the following figure.

ITimeCtl IAppletIDisplayIMenuCtlIModuleIShellITimeCtl

Allows the user to create and operate on ITimeCtl objects. The time control interface has three modes: clock, stop-watch, and count-down.


• Usage of the ITimeCtl interface.

itimectl.mifitimectlusage.moditimectlusage.sig

Resource application

IAppletIDisplayIImageIModuleIShell

Usage of BREW string and image resources.


• How to load a string using ISHELL_LoadResString() and display it using the IDisplay interface.

• How to load an image using ISHELL_LoadResImage() and display it using the IImage interface.

resapp.barresapp.mifresapp.modresapp.sig

Twin Applet IDisplayIShell

Demonstrate the presence of two applets within the same module. The module is called TwinApp1 and the two applets within this module are TwinApp1 and TwinApp2.


• How to create two applets in one BREW Module.

• How to process events meant for each applet.

• A sample MIF containing two applets.

twinapp.miftwinapp.modtwinapp.sig



67


NOTE: The phone skins displayed in this Guide are for illustration purposes only. The actual

phone skins shown may or may not by available with the BREW SDK at this time.

To develop an application, you need to create an application source code file. A sample source

file follows. Because each code segment of the file is explained in the table at the end of the

description of each sample application, few comments are added to the sample source code

listings.

Source code for Sample 1

1. #include "AEEModGen.h" // Module interface definitions2. #include "AEEAppGen.h" // Applet interface definitions3. #include "AEEDisp.h" // Display Interface definitions4. #include "helloworld.bid" // Applet ClassID5. 6. static boolean HelloWorld_HandleEvent(IApplet * pi, AEEEvent eCode, 7. uint16 wParam, uint32 dwParam);8.

68


9. // Applet loading function10. int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,11. IModule * po,void ** ppObj)12. {13. *ppObj = NULL;14. 15. if(ClsId == AEECLSID_HELLOWORLD)16. {17. if(AEEApplet_New(sizeof(AEEApplet), ClsId, pIShell,po, 18. (IApplet**)ppObj, (AEEHANDLER)HelloWorld_HandleEvent, 19. NULL) == TRUE)20. {21. return (AEE_SUCCESS);22. }23. }24. return (EFAILED);25. }26. 27. // The event handling function28. static boolean HelloWorld_HandleEvent(IApplet * pi, AEEEvent eCode, 29. uint16 wParam, uint32 dwParam)30. { 31. AECHAR szBuf[] = {'H','e','l','l','o','

','W','o','r','l','d','\0'};32. 33. AEEApplet * pMe = (AEEApplet*)pi;34. 35. switch (eCode) 36. {37. case EVT_APP_START: // Start Applet event38. IDISPLAY_ClearScreen (pMe->m_pIDisplay); // Erase Screen39. 40. // Display string on the screen41. IDISPLAY_DrawText(pMe->m_pIDisplay, AEE_FONT_BOLD, szBuf, 42. -1, 0, 0, 0, IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE); 43. IDISPLAY_Update (pMe->m_pIDisplay); // Flush output to

screen44. 45. return(TRUE);46. case EVT_APP_STOP:47. return TRUE;48. default:49. break;50. }51. return FALSE;52. }

69


The sample Hello World application uses a simple applet stub source file provided with the

BREW SDK. This file is compiled and linked with the applet and provides the necessary

interface required supporting the IModule and IApplet interfaces. This allows the application

developer to simply focus on handling a few of the BREW events passed to its HandleEvent

method. The application developer has the option of implementing all IModule and IApplet

interfaces directly that meet their needs more effectively.

In this example, the Hello World message is shown when the EVT_APP_START event is

received by the applet. This event is received by the application’s HandleEvent function when

the BREW AEE starts the applet. In this example the applet clears the screen, displays the

"Hello World" message, and instructs the display interface to update the screen.

This sample outlines just how easy it is to develop an applet under BREW. BREW isolates you

from all device-specific event processing. Although applets can elect to handle many events,

doing so is not a requirement of the AEE. This leaves you to concentrate on the functions

required by your application, rather than focusing on any device-specific requirements.

The following table provides a detailed description of the Hello World application source code.

Detailed description for Sample 1

Line numbers Description

1-3 The first four lines include files needed by the Hello World application.

• AEEModGen.h and AEEAppGen.h define the Module and Applet functions.

• The AEEDisp.h file includes the definitions of the IDisplay interface.

4 Line 4 includes the helloworld.bid file. This file contains the definition of the unique AEECLSID_HELLOWORLD ClassID of the applet. You have to use a value not used by another application. As stated previously, this value is reserved using the QUALCOMM BREW Interface Registry.

6-7 These lines are for forward declaration of the HandleEvent function prototype.

70


10-25 These lines define the standard load function that must be provided by all modules.

The Hello World applet is loaded into the Emulator as a DLL. This follows the dynamic loading model also used on the target device. To support this mechanism, the applet must export a single entry point into the module. Under the Emulator, this entry point is exported as a DLL entry point. Under the Device BREW environment, this function must be exported as follows:

• For statically linked modules (.LIB), the entry point must be given a unique name that can be added by the device integrator into the module table.

• For dynamically loaded modules (.MOD), the entry point must be located at the start of the first file linked.

The purpose of the AEEClsCreateInstance() function is to create an instance of the AEEApplet data structure for each applet or class supported by the module. The AEEApplet data structure is created by invoking the AEEApplet_New() function with the address of the applet specific handle event function. The first parameter is the size of the applet data structure. Because there is no data this applet needs to store, the AEEApplet data structure is used (see the resource application example for an applet-specific data structure use).

In the Hello World module, only one applet is supported. At line 17, the AEEApplet_New() function is invoked to create the AEEApplet data structure of the Hello World module.

Upon successful loading of the applet, AEE_SUCCESS is returned.


71


Sample 2: Using resources

This application introduces viewing images, moving images on the device screen, drawing

rectangles, and using keypress events.

When this applet starts, it prints two lines of text in the top half of the screen, with a 2-pixel-

wide horizontal line dividing the screen in the middle. In the following illustration, the two lines

of text read:

• Use arrow keys

• to move cursor

28-52 The HelloWorld_HandleEvent() function processes all the events the applet receives. The event type, subevent type, and event data are passed in the eCode, wParam, and dwParam parameters, respectively.

• The switch statement at line 35 looks at the main event received by the applet.

• If the event is EVT_APP_START, the applet has received a START event.

• The IDISPLAY_ClearScreen () function erases the whole screen.

• The IDISPLAY_DrawText () function is used to display the text string "Hello World" in the middle of the screen. The flags IDF_ALIGN_CENTER and IDF_ALIGH_MIDDLE are used to place the text string in the center of the screen along the horizontal and vertical axis, respectively.

• Finally, the IDISPLAY_Update () function is used to update the screen.

This application supports only two events, EVT_APP_START and EVT_APP_STOP. When the user presses the device’s END key, the applet receives the EVT_APP_STOP event. When this event is received by the applet, it needs to do applet-specific cleanup such as saving files, releasing memory allocated by applet, etc. Because the Hello World applet does not allocate any resources, there is no cleanup needed when the EVT_APP_STOP event is received.


72


You can move the cursor using the left, right, up, and down arrow keys, or using the navigation

button on the emulated device, if applicable.


1. #include "AEEModGen.h" // Module interface definitions2. #include "AEEAppGen.h" // Applet interface definitions3. #include "AEEShell.h" // Shell interface definitions4. #include "AEEDisp.h" // Display Interface definitions5. #include "AEEStdLib.h" // Standard library definitions6. #include "AEEImage.h" // IImage interface definitions7. #include "resapp_res.h" // Resource ID definitions8. #include "resapp.bid" // Applet ClassID9. 10. #define szResFile "resapp.bar" // Resource file name11. 12. // Applet specific data structure13. typedef struct _CResApp14. {

73


15. AEEApplet a; // Mandatory AEEApplet data member appears first16. int m_cxWidth; // Stores the device screen width17. int m_cyHeight; // Stores the device screen height18. int m_nCursorX; // Stores the cursor bitmap x coordinate19. int m_nCursorY; // Stores the cursor bitmap y coordinate20. IImage * m_pIImage; // IImage interface pointer21. }CResApp;22. 23. static boolean ResApp_HandleEvent(IApplet * pi, AEEEvent eCode,

uint16 24. wParam, uint32 dwParam);25. static boolean ResApp_InitAppData(IApplet* pMe);26. static void ResApp_FreeAppData(IApplet* pMe);27. static void CresApp_Move(CResApp * pMe, int xc, int yc);28. 29. // Mandatory applet loading function30. int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * 31. po,void ** ppObj)32. {33. *ppObj = NULL;34. 35. if(ClsId == AEECLSID_RESAPP){36. if(AEEApplet_New(sizeof(CResApp), ClsId, pIShell, po, 37. (IApplet**)ppObj, (AEEHANDLER)ResApp_HandleEvent, 38. (PFNFREEAPPDATA)ResApp_FreeAppData) == TRUE)39. {40. if (ResApp_InitAppData((IApplet*)*ppObj) == TRUE)41. {42. return(AEE_SUCCESS);43. }44. }45. }46. return (EFAILED);47. }48. 49. // Applet data initializing function50. static boolean ResApp_InitAppData(IApplet* pi)51. {52. AEEDeviceInfo di;53. CResApp * pMe = (CResApp*)pi;54. 55. pMe->m_pIImage = NULL;56. 57. if (pMe->a.m_pIShell) { 58. ISHELL_GetDeviceInfo(pMe->a.m_pIShell, &di); // Get device info59. pMe->m_cxWidth = di.cxScreen;60. pMe->m_cyHeight = di.cyScreen;61. }62. 63. pMe->m_nCursorX = pMe->m_cxWidth/2;64. pMe->m_nCursorY = pMe->m_cyHeight*2/3;65. 66. // Load image resource and store in applet struct data member67. if ((pMe->m_pIImage = ISHELL_LoadResImage(pMe->a.m_pIShell,

74


68. szResFile, IDB_CURSOR)) == NULL)69. {70. return FALSE;71. }72. 73. return TRUE;74. }75. 76. // Applet data freeing function77. static void ResApp_FreeAppData(IApplet* pi)78. {79. CResApp * pMe = (CResApp*)pi;80. 81. if (pMe->m_pIImage != NULL)82. {83. IIMAGE_Release (pMe->m_pIImage);84. }85. }86. 87. // Event handling function88. static boolean ResApp_HandleEvent(IApplet * pi, AEEEvent eCode,

uint16 89. wParam, uint32 dwParam)90. { 91. AEERect rc;92. AECHAR szBuf[30] = {0};93. 94. CResApp * pMe = (CResApp*)pi;95. 96. switch (eCode) 97. {98. case EVT_APP_START: // Applet start event99. IDISPLAY_ClearScreen (pMe->a.m_pIDisplay); // Erase screen100. // Load string "Use arrow keys" from resource file.101. ISHELL_LoadResString(pMe->a.m_pIShell, APP_RES_FILE, 102. IDS_STRING1, szBuf, sizeof (szBuf));103. IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL,

szBuf, 104. -1, pMe->m_cxWidth/5, pMe->m_cyHeight/8, 0, 0);105. 106. // Load string "to move cursor" from resource file.107. ISHELL_LoadResString(pMe->a.m_pIShell, APP_RES_FILE, 108. IDS_STRING2, szBuf, sizeof (szBuf));109. IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL,

szBuf, 110. -1, pMe->m_cxWidth/5, pMe->m_cyHeight/5, 0, 0);111. 112. // Initialize rectangle113. SETAEERECT (&rc, 0, pMe->m_cyHeight/2 - 2, pMe->m_cxWidth,

2); 114. IDISPLAY_DrawRect (pMe->a.m_pIDisplay, &rc, 0, 1, 115. IDF_RECT_FILL);116. // Draw cursor bitmap image on screen117. IIMAGE_Draw (pMe->m_pIImage, pMe->m_nCursorX,

75


118. pMe->m_nCursorY);119. 120. IDISPLAY_Update(pMe->a.m_pIDisplay);121. return (TRUE);122. case EVT_KEY: // process key-down event123. switch (wParam)124. {125. case AVK_LEFT:126. case AVK_RIGHT:127. CresApp_Move(pMe,(wParam == AVK_RIGHT ? 1 : -1), 0);128. break;129. case AVK_UP:130. case AVK_DOWN:131. CresApp_Move(pMe,0,(wParam == AVK_UP ? -1 : 1));132. break;133. default:134. return(FALSE);135. }136. return(TRUE);137. case EVT_APP_STOP:138. return TRUE;139. default:140. break;141. }142. 143. return FALSE;144. }145. 146. // Helper function to move bitmap on the screen147. static void CresApp_Move(CResApp * pMe, int xc, int yc)148. {149. AEEImageInfo iInfo;150. int min, max;151. int x = pMe->m_nCursorX;152. int y = pMe->m_nCursorY;153. 154. IIMAGE_GetInfo (pMe->m_pIImage, &iInfo); // Get image info155. 156. // Erase previously displayed bitmap from the screen157. IDISPLAY_EraseRgn (pMe->a.m_pIDisplay, x, y, iInfo.cx, iInfo.cy);158. 159. x += xc;160. y += yc;161. 162. // Delimit the x & y coordinates to lower half of the screen163. min = 0;164. max = pMe->m_cxWidth - iInfo.cx;165. x = ((x < min) ? (min) : (x > max) ? max : (x));166. 167. min = pMe->m_cyHeight/2;168. max = pMe->m_cyHeight - iInfo.cy;169. y = ((y < min) ? (min) : (y > max) ? max : (y));170. 171. IIMAGE_Draw (pMe->m_pIImage, x, y); // Display bitmap image

76


172. 173. pMe->m_nCursorX = x; // Store new x coordinates174. pMe->m_nCursorY = y; // Store new y coordinate175. 176. IDISPLAY_Update(pMe->a.m_pIDisplay); // Update screen177. }

The data structure of sample application #2 is applet-specific. It needs to declare as its first

data member an instance of the AEEApplet class. This is a strict requirement that gives the

BREW AEE the ability to load applets dynamically. You need to add the applet-specific data

member following the AEEApplet instance.



1-8 A new header file, resapp_res.h, is included to get the resource IDs for the new applet.

• AEEStdlib.h is included to access standard conversion routines.

• AEEImage.h is added to include image processing functions.

10 A resource filename is defined. This resource file contains all the resources used in this example.

13-21 An applet-specific data structure is defined here to store all the applet data that needs to be remembered through the life of the application. The major requirement this data structure has is that its first data member needs to be an instance of type AEEApplet. This requirement is related to an applet being dynamically downloaded.

23-27 These lines are for forward declaration of functions.

• FreeAppData and InitAppData are declared here. The latter function, which was not used in the Hello World example, is used here because there is applet-specific data that must be initialized and released.

• The helper function CresApp_Move is declared here. This helper function moves an image in a given direction.

30-47 These lines define the standard load function each module needs to supply.

• AEEApplet_New function is invoked to load the applet. Here the first parameter to this function is the size of the applet data structure.

NOTE: Unlike the Hello World applet, the applet data structure size is passed instead of AEEApplet size.

• When an applet is loaded successfully, the InitAppData function is invoked at line 40 to initialize applet-specific data.

77


50-74 This section defines the InitAppData function, used to initialize applet-specific data.

• Use the ISHELL_GetDeviceInfo function to get the device screen width and height and store them in the applet data structure.

• Initialize the location coordinates of the cursor on the screen. The device screen width and height are used so that the cursor image is located halfway along the x-axis and 2/3 of the way along the y-axis.

• Load the resource image from the resource file and store a pointer to it in the m_pIImage data member.

77-85 This section defines the FreeAppData function, which frees the image object stored in the applet data structure.


78


88-144 These lines define the applet HandleEvent function.

• Under the EVT_APP_START event, a local AEERect object with screen dimensions is initialized.

• The whole screen is erased using the IDISPLAY_ClearScreen function.

• The resource string Use arrow keys is loaded from the application resource file using IDS_STRING1 string ID. This string is copied to a local AECHAR type string buffer, szBuf. APP_RES_FILE defines the application resource filename.

• The IDISPLAY_DrawText function displays the string in the szBuf buffer on the screen at x and y coordinates of screen-width/5 and screen-height/8. These coordinates roughly correspond to a location in the middle of the top half of the screen.

• A second resource string, "to move cursor,” is loaded from the application resource file using IDS_STRING2 string ID. This string is also written to szBuf buffer.

• The second string is displayed on the screen (similar to the above step) using the IDISPLAY_DrawText function, where the location of the y coordinate is screen-height/5, which roughly places the second string right below the first string on the screen.

NOTE: These locations vary depending on the screen dimensions.

• A rectangle object of type AEERect is initialized using the SETAEERECT function, where the second and third parameters are the x and y coordinates of the rectangle’s upper left corner, and fourth and fifth parameters are the height and width of the rectangle. These values correspond to a 2-pixel-wide rectangle in the middle of the screen. This rectangle is used to draw a thin horizontal line across the screen, dividing the screen in half.

• The IIMAGE_Draw function is used to display the cursor in the lower half of the screen (using coordinates initialized in the InitAppData function). The IDISPLAY_Update function is used to flush the text buffers onto the screen.

• Under the EVT_KEY event, the AVK_LEFT, AVK_RIGHT, AVK_UP, and AVK_DOWN key press subevents are switched on, and the CresApp_Move function is called to move the cursor in the direction corresponding to the keypress.


79


Sample 3: Using timers and alarms

This example application demonstrates the use of timers and alarms. It sets a timer that

expires in 10 seconds and an alarm that is activated in 10 minutes. The example also shows

how multiple BREW applets can be defined within the same application. When the timer

expires, a callback function is invoked to process it. Activation of the alarm causes an

EVT_ALARM event to be sent to a designated BREW class (in this example, it is sent to a

separate alarm-handling applet). Upon receiving the EVT_ALARM event, an instance of the

class is created to handle the event.


1. #include "AEEAppGen.h"2. #include "AEEModGen.h"3. #include "AEEShell.h"4. 5. #define AEECLSID_TIMERAPP 0x0100FF026. #define AEECLSID_ALARMAPP 0x0100FF037. 8. static boolean TimerApp_HandleEvent(IApplet * pi, AEEEvent eCode, 9. uint16 wParam, uint32 dwParam);10. static boolean AlarmApp_HandleEvent(IApplet * pi, AEEEvent eCode, 11. uint16 wParam, uint32 dwParam);

147-177 These lines define a helper function, which takes an applet data structure pointer and two integer variables corresponding to incremental movement of the cursor in the x and y directions.

• Two local variables (x and y) are initialized with the present cursor location coordinates.

• The IIMAGE_GetInfo function gets the image information.

• The IDISPLAY_EraseRgn function erases the region where the cursor was previously displayed.

• The local x and y variables are updated with the new position of the cursor.

163-169 These lines use algorithms to evaluate if the new cursor coordinates are within the boundaries of the bottom half of the screen, delimiting the cursor to the bottom half of the screen.

• The IIMAGE_Draw function is used to display the cursor at the new coordinates.

• The new coordinates are stored in the applet data structure members, and the device screen is updated using the IDISPLAY_Update function.


80


12. 13. static void TimerApp_FreeAppData(IApplet* pMe) {}14. static void AlarmApp_FreeAppData(IApplet* pMe) {}15. 16. int AEEClsCreateInstance(AEECLSID ClsId, IShell* pIShell, 17. IModule* po, void** ppObj)18. {19. *ppObj = NULL;20. 21. if(ClsId == AEECLSID_TIMERAPP)22. {23. if(AEEApplet_New(sizeof(AEEApplet), ClsId, pIShell,po,24. (IApplet**)ppObj, (AEEHANDLER)TimerApp_HandleEvent,25. (PFNFREEAPPDATA)TimerApp_FreeAppData) == TRUE)26. {27. return(AEE_SUCCESS);28. }29. }30. else if(ClsId == AEECLSID_ALARMAPP)31. {32. if(AEEApplet_New(sizeof(AEEApplet), ClsId, pIShell,po,33. (IApplet**)ppObj, (AEEHANDLER)AlarmApp_HandleEvent,34. (PFNFREEAPPDATA)TimerApp_FreeAppData) == TRUE)35. {36. return(AEE_SUCCESS);37. }38. }39. return (EFAILED);40. }41. 42. // Timer Callback Function43. void TimerCB(void *pv)44. {45. AEEApplet * pMe = (AEEApplet *) pv;46. 47. // Process timer expiration here48. 49. }50. 51. static boolean TimerApp_HandleEvent(IApplet *pi, AEEEvent eCode, 52. uint16 wParam,uint32 dwParam)53. {54. AEEApplet * pMe = (AEEApplet *)pi;55. int timerValue = 10000; // 10000 milliseconds56. uint16 nCode = 10;57. uint32 numMinutes = 10; // Alarm activate time: 10 minutes58. 59. switch (eCode)60. {61. // Handle app startup62. case EVT_APP_START: // Process Start event 63. 64. // Set timer65. ISHELL_SetTimer (pMe->m_pIShell, timerValue,

81


66. TimerCB, (void *)pMe);67. 68. // Now set alarm69. ISHELL_SetAlarm (pMe->m_pIShell, AEECLSID_ALARMAPP, nCode,70. numMinutes);71. 72. return (TRUE);73. 74. case EVT_APP_STOP: // Process Stop event75. 76. // If timer is still running, cancel it77. if (ISHELL_GetTimerExpiration (pMe->m_pIShell, TimerCB, 78. (void *)pMe) > 0)79. ISHELL_CancelTimer (pMe->m_pIShell, TimerCB, (void

*)pMe);80. 81. // Cancel alarm (alarm is still active since we are still in82. // Timer Applet)83. ISHELL_CancelAlarm (pMe->m_pIShell, AEECLSID_ALARMAPP,

nCode);84. 85. return(TRUE);86. }87. return(FALSE);88. }89. 90. static boolean AlarmApp_HandleEvent(IApplet *pi, AEEEvent eCode, 91. uint16 wParam,uint32 dwParam)92. {93. AEEApplet * pMe = (AEEApplet *)pi;94. 95. switch (eCode)96. {97. // Handle alarm 98. case EVT_ALARM: // Process Alarm event 99. 100. // Process Alarm event101. 102. return (TRUE);103. }104. return(FALSE); 105. }

82




1-3 The first three lines include files needed by the timer/alarm application.

• AEEModGen.h and AEEAppGen.h define the module and applet functions.

• AEEShell.h includes all the definitions that an application needs to work with the IShell interface.

5-6 Defines the ClassIDs of the two applets in this application. The timer applet (AEECLSID_TIMERAPP) sets an alarm and a timer. When the alarm is activated, the alarm applet (AEECLSID_ALARMAPP) receives the EVT_ALARM event, at which time the applet is loaded to process it.

8-14 Forward declarations of the HandleEvent and FreeAppData functions for each applet are presented here. Because neither applet has any data that needs to be freed upon termination, both their FreeAppData functions are empty.

16-40 These lines define the standard load function that must be provided by all modules. In this application, the function can load either the timer or alarm applet, based on the ClassID that is passed to it. The timer applet is loaded when the device user requests execution of the applet, while the alarm applet is loaded to process the EVT_ALARM that is generated when the alarm is activated.

42-49 TimerCB is the callback function for the timer that is set when the timer applet is started. When setting a timer, you specify the address of the timer’s callback function and a 32-bit variable that is the single parameter of this function. In this example, a pointer to the timer applet’s AEEApplet structure is passed to TimerCB. When the timer expires, this function is invoked. The callback function is empty in this example, but it usually contains any processing that must be performed upon expiration of the timer.

83


Sample 4: Using files

This subsection describes the use of the IFileMgr and IFile interfaces. Because several

complete examples of BREW applications have already been presented, the next example

shows only the portions of the code that are of specific interest.

This example demonstrates the use of the IFileMgr and IFile interfaces to open a file and read

data from it. The code author has assumed that the interface pointers in this example are used

by several parts of the program; therefore, they are part of the applet data structure.

The declaration of the applet data structure and the HandleEvent function of the example are

shown in the following sample source code. Other portions of the program have been omitted.

51-88 These lines contain the HandleEvent function of the timer applet. This applet supports the EVT_APP_START and EVT_APP_STOP events.

When it receives the EVT_APP_START event, the timer applet first starts a timer, specifying the expiration time (10,000 milliseconds, or 10 seconds), and the address (TimerCB) and parameter (pMe, the timer applet’s AEEApplet structure) of the callback function. The applet then sets an alarm, providing the ClassID (AEECLSID_ALARMAPP) of the alarm applet, a 16-bit code identifying the alarm (this code allows multiple alarms destined for the same class to be active at once), and the number of minutes (10 in this case) until the alarm is activated.

This applet also processes the EVT_APP_STOP event, which would be generated if the device user chose to terminate the applet before the timer and/or alarm have been activated. In this case, the applet cancels the timer if it is still running, and then cancels the alarm.

90-105 These lines contain the HandleEvent function of the alarm applet. This applet processes only the EVT_ALARM event. When it receives this event, the wParam parameter of the HandleEvent function contains the 16-bit code that was supplied by the timer applet when it sets the alarm. Here the applet can perform any processing associated with the alarm activation (no processing is shown in this example). Note that once it completes processing of the alarm, the alarm applet is terminated. If an applet that is loaded just to process an alarm event needs to interact with the device user, it can send itself an EVT_APP_START by calling its own HandleEvent function. This allows the applet to write to the device display and receive keypad input from the user.


84



1. typedef struct _CFileApp {2. AEEApplet a; // Mandatory first member of structure3. 4. // Begin applet-specific data5. IFileMgr * m_pIFileMgr;6. IFile * m_pIFile;7. } CFileApp;8. 9. ………………………10. 11. // HandleEvent Function12. static boolean FileAppHandleEvent (IApplet * pi, AEEEvent eCode,13. uint16 wParam, uint32 dwParam)14. {15. CFileApp * pMe = (CFileApp *) pi;16. 17. OpenFileMode mode = _OFM_READ; // Mode in which file opened18. byte pBuffer[100]; // Buffer to read data into19. uint32 dwCount = 100; // Number of bytes to read20. char szFileName[] = “fileName”; // Name of file to be opened21. 22. switch (eCode)23. {24. // Handle applet startup25. case EVT_APP_START:26. 27. // Create an instance of the file manager28. ISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_FILEMGR,29. (void **) pMe->m_pIFileMgr);30. 31. if (pMe->m_pIFileMgr)32. {33. // Open the file for reading34. if (pMe->m_pIFile = IFILEMGR_OpenFile(pMe->m_pIFileMgr,35. szFileName, mode))36. {37. // Succeeded in opening file for reading, so now38. // read first 100 bytes of file into buffer39. if (IFILE_Read(pMe->m_pIFile, pBuffer, dwCount) == 0)40. {41. // Read failed—close the file and exit42. IFILE_Release(pMe->m_pIFile);43. return FALSE; // read failed44. }45. }46. // Close the file now that we’ve finished accessing it47. IFILE_Release(pMe->m_pIFile);48. }49. return TRUE;50. 51. case EVT_APP_STOP:52. break;

85


53. }54. return FALSE;55. }


Sample 5: Using databases

This subsection describes the use of database operations. As in the previous example, an

applet-specific data structure is created to hold the applet data, and an AEEApplet instance at

the beginning of the structure. Pointers to the IDBMgr, IDatabase, and IDBRecord interfaces

are declared following the AEEApplet instance.


1-8 The declaration of the applet data structure includes the mandatory AEEApplet structure as its first member, followed by the applet-specific IFileMgr and IFile instance pointers. Declaring the pointers here makes them available to other parts of the program by passing them a pointer to the applet data structure. For example, an instance of IFileMgr is created when the applet is started (see below), and this instance can be used by any other applet function that needs it. This instance could be freed in the applet’s FreeAppData function (not shown).

11-20 This is the beginning of the applet’s HandleEvent function. Some variables that are used as parameters in the function calls in the body of HandleEvent are declared and initialized here.

22-30 The applet tries to read the file when it receives the start event. It first attempts to create an instance of the IFileMgr interface. If this succeeds, the instance pointer returned by ISHELL_CreateInstance has a nonzero value.

31-35 If an instance of IFileMgr was created successfully, the applet next tries to open the specified file for reading. If this succeeds, IFILEMGR_OpenFile returns a pointer to an IFile interface, which can be used to perform read operations on the opened file.

36-45 If IFILEMGR_OpenFile returns a non-NULL file pointer, the applet can then call IFILE_Read to read the specified number of bytes from the start of the file into the buffer. IFILE_Read returns the number of bytes read, so if it returns 0 (zero), the IFile instance is released and an indication of applet startup failure is returned.

46-49 If this point is reached, you can assume that the read was successful. The IFile instance (which closes the file opened in lines 34-35) is then released and success is returned. The instance of IFileMgr created in lines 28-29 has not been released because other parts of the program need it. (It can be released with the applet’s FreeAppData function.)

86


The applet-specific data structure is listed below.

typedef struct _CDBApp{ AEEApplet a; // Mandatory AEEApplet data member appears first IDBMgr * m_pIDBMgr; IDatabase * m_pIDatabase; IDBRecord * m_pIDBRecord;}CDBApp;

As in the previous example, only the event handling function is listed. The

AEEClsCreateInstance function is similar to the one found in the first three examples. The

InitAppData function initializes the three database-related pointers and the FreeAppData

releases them.


1. static boolean DBApp_HandleEvent(IApplet * pi, AEEEvent eCode, uint162. wParam, uint32 dwParam)3. { 4. const char szDbFileName [] = "dbFileName"; // Database file name5. AEEDBField dbField[1]; // Database field data instance6. int nNumFields = 1; // Number of fields in the record7. const char lastName [] = "Smith"; // Last name of a person8. CDBApp * pMe = (CDBApp*)pi;9. 10. switch (eCode) 11. {12. case EVT_APP_START:13. // Initialize DB record field to store a last name.14. dbField[0].fType = AEEDB_FT_STRING;15. dbField[0].fName = AEEDBFIELD_LASTNAME;16. dbField[0].wDataLen = STRLEN (lastName);17. dbField[0].pBuffer = (void *)&lastName;18. 19. // Create an instance of the Database manager20. ISHELL_CreateInstance (pMe->a.m_pIShell, AEECLSID_DBMGR, 21. (void **)pMe->m_pIDBMgr);22. 23. if (pMe->m_pIDBMgr)24. {25. //Open Database26. if ((pMe->m_pIDatabase = IDBMGR_OpenDatabase (27. pMe->m_pIDBMgr, szDbFileName, TRUE)))28. {29. // Create database record30. if ((pMe->m_pIDBRecord = IDATABASE_CreateRecord (31. pMe->m_pIDatabase, dbField, nNumFields))) 32. {33. return TRUE;34. }

87


35. }36. }37. return FALSE;38. case EVT_APP_STOP:39. return TRUE;40. default:41. break;42. }43. 44. return FALSE;45. }

The previous example creates a database record with one field to hold the last name of a

person. A detailed description of the Handle-Event function of the example follows.



4-7 The following declarations are made:

• a string to represent the database filename.

• an AEEDBField object to represent a field in the database record.

• a string to be used as the last name of a person.

14-17 Datafill the database field instance with the field type, name, data length, and a pointer to the data.

20 Create an instance of the database manager by calling ISHELL_CreateInstance function with the AEECLSID_DBMGR ClassID.

26-27 If the database manager was created successfully, create a database of the given name using the IDBMGR_OpenDatabase function. The final parameter of this function indicates whether a new database is to be be created when the specified database file does not exist: When set to TRUE, a new database is created; when set to FALSE, no new database is created.

30-31 If the database record was created successfully, invoke the IDATABASE_CreateRecord function to create a database record. A pointer to the dbField object is passed to this function to create the database record.

88


Sample 6: Using sockets

This section provides a procedure for an application to read from a socket.

To force an application to read from a socket

1. Obtain an instance of the INetMgr interface using the ISHELL_CreateInstance()

function invoked with the AEECLSID_NET ClassID.

2. Open a socket using the INETMGR_OpenSocket() function.

3. Connect the socket to a specific address using the INETMGR_Connect() function,

and specify a callback function address, which is called when the connection is

successful.

4. When the Connect callback is called, perform a read operation on the socket using

the ISOCKET_Read() function.

5. If the function returns the value AEE_NET_WOULDBLOCK, indicating that the

socket would block, register a callback function with the socket for read operations

using the ISOCKET_Readable() function.

When the socket is ready to be read, this callback is invoked. Inside the callback,

the data can be read using ISOCKET_Read(). The AEE Sockets always operate

in the asynchronous mode.

6. Repeat the previous steps until the required number of bytes have been read.

7. Close the socket using the ISOCKET_Release() function.

8. When the INetMgr interface is no longer needed, release the INetMgr by invoking

the INETMGR_Release() function.

For the complete source code, see the sample applications in the Examples directory of the

BREW SDK.

89

Using Dialogs and Controls

A dialog is a frame that contains controls. BREW controls are graphical and textual interfaces

that provide input and output functions for BREW. The following types of controls are

supported:

• Clock

• Countdown

• Date

• Date Pick

• Icon View

• List

• Menu

• Soft Key

• Stopwatch

• Text

Creating dialogs

There are two ways to create a dialog:

• using the Resource Editor

• constructing the dialog manually by creating data structures in your application to

define the contents of the dialog

Using the Resource Editor to create a dialog

You must create a dialog resource before you can use the Resource Editor to create dialog

objects.

90


To create a dialog resource

1. Start the Resource Editor.

The BREW Resource Editor window opens.

2. Choose Resource > New Dialog.

The Dialog Resource dialog box opens.

91


With the Resource Editor, you can specify the coordinates, size, and types of

controls to be placed on a dialog. The following example shows the Menu control.

For detailed instructions on creating BREW dialogs and controls with the Resource

Editor, see the BREW Resource Editor Guide.

After the appropriate resource files are generated, you must call the ISHELL_CreateDialog

function using the following parameters:

• Pointer to the IShell object

• BREW resource file (.bar) name

• Resource ID of the dialog

Constructing the dialog manually

If you prefer, you can construct a dialog object without first creating a BREW dialog resource.

In this case, you need to provide the DialogInfo structure defined in the AEEShell.h file. To

construct a DialogInfo object, you must also create DialogItem objects and DListItem objects

(also defined in AEEShell.h). The DialogItem structure defines dialog controls, while the

DListItem structure defines list items, which are the choices presented in the controls.

After you have created the appropriate structures, call the ISHELL_CreateDialog function

using the following parameters:

• Pointer to the IShell object

• Pointer to the DialogInfo object

The return value can be one of the following:

• SUCCESS indicates that the dialog was created successfully.

• EBADCLASS indicates that the pointer to the IShell object was invalid.

• ENOMEMORY indicates that the device has insufficient memory.

• EBADPARM indicates that one or more parameters passed into the function is

invalid.

92


Dialog events

The following three events can be handled by any applet that uses BREW dialogs:

The applet is not required to do any specific processing in response to these events in the

applet event handler; however, it is recommended that appropriate initialization or cleanup be

performed.

In addition to these three events, the applet can also handle those events of type

EVT_COMMAND specified in the dialog control and list items.

Dialog controls

To retrieve an interface pointer to a control in a newly created dialog, use the

ISHELL_GetControl function. To use this function, you must provide the ID of the control (the

same ID you used to create the control). The signature of the function looks like this:

IControl IDIALOG_GetControl(pIDialog, int16 wID);

where pIDialog is the pointer to the dialog object, and int16 wID is the ID of the control.

The return value is the pointer to the control object. If the control ID isn’t valid, the return value

is set to NULL. After this pointer is obtained, you can manipulate the control objects by calling

each control’s interface functions.

EVT_DIALOG_INIT This event is sent to the applet after the BREW dialog object verified the passed in parameters and is initialized correctly. No event-specific parameter is passed in with this event.

EVT_DIALOG_START This event is sent to the applet after all the dialog Controls and List Items are loaded and the screen is refreshed to show the dialog. The following parameters are passed in with the event:

• dParam: The first event parameter contains the ID of the dialog.

• dwParam: The second event parameter contains the pointer to the dialog.

EVT_DIALOG_END This event is sent to the applet after the dialog is destroyed. The following parameters are passed in with the event:

• dParam: The first event parameter contains the ID of the dialog.

• dwParam: The second event parameter contains the pointer to the dialog.

93


The IDIALOG_SetFocus function lets you specify which control in a multicontrol dialog has the

focus. This control receives key input from the device user.

The prototype of the function looks like this:

int16 IDIALOG_SetFocus(pIDialog, int16 wID);

where pIDialog is the pointer to the dialog object, and int16 wID is the ID of the control.

The return value is the ID of the control that had the active focus just prior to the function call.

For descriptions of each control, see the BREW Resource Editor Guide. For functions

associated with each control, see the BREW API Reference.

Terminating dialogs

When a dialog object is no longer needed, terminate it through the ISHELL_EndDialog

function must be called with the Pointer to the IShell object parameter.

The ISHELL_EndDialog function terminates the active dialog in the event that more than one

dialog object is open. The return value of this function varies based on the success of the

dialog termination. Possible return values are as follows:

• SUCCESS indicates that the function has properly terminated the active dialog

object.

• EBADCLASS is an error code, which is returned when the pointer to the IShell

object is not valid.

• EFAILED indicates that there was no active dialog to process.

After the termination is complete, the EVT_DIALOG_END dialog event is sent to the applet.

When the event is received, the applet takes appropriate actions to ensure that all references

to the old active dialog are also removed.

Dialog application example

In the following procedure, you will create an example application with a dialog using the

Resource Editor. The dialog includes a menu from which the user to choose a favorite color

from a list of five choices.

94


To create the “Favorite Color” application

1. Using the MIF Editor, create a MIF. See the BREW MIF Editor Guide for information

and instructions.

2. Using the Resource Editor, create String resources, entering the text strings shown

below:

3. Create Dialog resources by doing the following:

a. Create a main Dialog resource as shown below:

b. Provide the details of the dialog resource as shown below.

The dialog resource contains one menu control.

95


c. Provide the details of the menu control as shown below.

The menu control has list Items representing the color choices.

See the source code for the SampleDialog applet and IDialog usage applet shipped with the

BREW SDK.

96


The new application’s initial dialog looks like the device on the left, and each selection presents

a selection confirmation message box like the one shown on the right.

97

Using the BREW Emulator

The Emulator emulates a selected handheld device, allowing you to load and test applets and

classes developed in the BREW environment. The wireless devices emulated can have

different screens, keypads, amounts of available memory, and supported languages. During

emulation, the Emulator opens an image of the device on a PC monitor. By clicking the

portions of the image that correspond to the device’s keys, you provide key input to the applet

being emulated, and the screen output produced by the applet appears in the screen portion

of the device image.You have the option of viewing your applications at the device’s actual

screen size or specifying a screen size in the configuration file in the Configurator. See the

BREW Device Configurator Guide for more information. The BREW SDK also includes several

sample applets that you can load into the Emulator and explore.

Running the Emulator

When you run the Emulator, it opens the image of the device defined in the device

configuration file (.qsc). The Emulator searches the specified MIF directory and shows a list of

all applets with MIFs in that directory. The MIFs contain icons for each applet.

When you choose an applet from the list, the Emulator loads the applet’s DLL and executes

the applet, showing its initial screen on the device screen. You can click the device keys to

provide input to the applet and observe its behavior, including its output to the screen.

Before beginning to develop applications with BREW, try running devices on the Emulator.

You’ll discover this is an invaluable tool for learning about programming in the BREW

environment. See Running sample applications on page 105 for information.

There are two methods for running the Emulator, from the Windows Start menu and from the

command line.

To run the Emulator from the Start menu

1. Choose Start > Programs > BREW > BREW Emulator.

The BREW Emulator window opens. BREW automatically starts the Application

Manager, which shows a menu of icons and an applet name on the device screen.

98


NOTE: The phone skins displayed in this Guide are for illustration purposes only.

The actual phone skins shown may or may not by available with the BREW SDK

at this time.

Applets

Selectkey

Clearkey

Endkey

99


2. Depending on the selected device, you can use your keyboard arrow keys to move

between applet icons, or you can click on the navigation buttons on the emulated

device. In the device shown above, the Select button allows you to move left, right,

up, and down.

To run the Emulator from the command line

1. If a command prompt window is not already open, do one of the following to open

one:

• For Windows 2000, choose Start > Programs > Accessories > Command Prompt.

• For Windows NT, choose Start > Programs > Command Prompt.

2. At the command prompt, navigate to <BREW\Bin>.

3. Type the following command:

BREW_Emulator [-d <DeviceFile>] [-a <AppDir>] [-m <MifDir>]

where:

<DeviceFile>, corresponding to the -d option, is the full device filename (including

its path) for the initial device.

<AppDir>, corresponding to the -a option, is the path to the application directory.

<MifDir>, corresponding to the -m option, is the path to the MIF directory.

NOTE: If any of the paths contain spaces, you must enclose the path with quotation

marks. For example, if you type the <MifDir> path C:\Program Files\BREW

\Examples\MIF\Apps\256Color\, all characters in the path after the word Program

would be ignored. The correct way to type the path is: “C:\Program

Files\BREW\Examples\MIF\Apps\256Color\.”

The BREW_Emu.dat settings file, stored in the <BREW\Bin> directory, is updated

when you are editing the Settings dialog box in the Emulator. If you enter an invalid

path, the path defaults to the one saved in the BREW_Emu.dat file. The settings

file can be changed only by directly editing it with a text editor like Notepad or by

changing the path in the Settings dialog box.

Emulator menus and other features

The Emulator has four menus (File, View, Tools, and Help), which are described on the

following pages.

100


File menu

Load Device... Opens the Select Device dialog box which, by default, lists preconfigured device files in the <BREW\Devices> directory. These device configuration files were created with the Configurator. For more details on device files, see BREW SDK directory structure.

Change Applet Dir... Opens the Select Applet Directory dialog box so that you can change the applet directory where the Application Manager searches for applets. For more information about the applet directory, see BREW SDK directory structure.

101


Change MIF Dir... Opens the Select MIF Directory dialog box so that you can change the MIF directory where the Application Manager searches for MIFs of the applets. For more details on the MIF directory, see BREW SDK directory structure.

Exit Closes the Emulator.

102


View menu

Tools menu

Real Size Screen Toggles between the device's actual screen size and the Emulator's default screen size. When you create a device configuration file using the Configurator, you have the option of specifying the width and height of the device screen. Then, when the device is loaded into the Emulator, choosing Real Size Screen from the View menu lets you match the Emulator's display size with the size of the actual device screen to obtain a more accurate emulation of device output behavior. This feature of the Emulator is available only if you entered the physical dimensions of the device screen when you created the device configuration file.

Output Window Displays messages that can be valuable for debugging your software when it is displayed using the Emulator. Any code marked for tracing within the software can cause messages to be shown in this window.

Settings... Opens the Settings dialog box, which allows you to select the initial device file, initial applet directory, and initial MIF directory. The Emulator saves the settings in a data file and uses the saved settings when the Emulator is restarted. Changes made to the settings take effect immediately.

103


Click Select Device File... to open the Select Device dialog box.

Click Select App Dir... to open the Select Applet Directory dialog box in order to enter the initial applet directory.

Click Select MIF Dir... to open the Select MIF Directory dialog box in order to enter the initial MIF directory.

NOTE: In the Emulator, the length of paths, including the filenames, cannot exceed 256 characters.

Speed Emulation Opens a menu with the following two options.

Enable Toggles speed emulation on and off for the selected device. This option is available only for devices configured for speed emulation in the Configurator. See BREW Device Configurator for details.

Tune Parameters Calculates the emulated speed of a device that you have configured for speed emulation. This menu option is available only if you have disabled speed emulation for the device in the Emulator. For more information, see Tuning speed emulation parameters and enabling the device on page 113.

TAPI Emulation Allows you to emulate incoming or outgoing calls, or send SMS messages to BREW. This allows you to test the effect of incoming calls when applications you have written are running. For more information, see Using TAPI emulation on page 114.

Enable Key Beep Allows you to emulate the Dual Tone Multi-Frequency (DTMF) tones for the selected device. The device’s key pad has been mapped to generate the DTMF tones corresponding to those on the actual device. This menu option toggles on and off.

104


Help menu

Backlight toggle

Clicking the right mouse button anywhere on the Emulator screen opens a menu that contains

an option to toggle the backlight of the screen between dark and light. This feature is available

for monochrome devices only. It is not supported by color devices.

Color support in the Emulator

The Emulator supports 1-monochrome, 4-grayscale, 16-color, and 256-color. The color depth

information is obtained from the BREW device file for any given device. To use the color

feature of the Emulator, you must use the Configurator to create a BREW device file with

corresponding color depth. A list of color depths and their associated colors follows.

Color depth of 2:

Color depth of 4:

About BREW Emulator Opens a window that shows the BREW version and copyright information.

RGB (0, 0, 0) Black

RGB (0x80, 0x80, 0x80) Dark Grey

RGB (0xc0, 0xc0, 0xc0) Light Grey

RGB (0xff, 0xff, 0xff) White

RGB (0x00, 0x00, 0x00) Black

RGB (0x80, 0x00, 0x00) Dark Red

RGB (0x00, 0x80, 0x00) Dark Green

RGB (0x80, 0x80, 0x00) Dark Yellow

RGB (0x00, 0x00, 0x80) Dark Blue

RGB (0x80, 0x00, 0x80) Dark Magenta

105


Color depth of 8: BREW supports 216 (6x6x6) colors uniformly distributed in the RGB color

cube, in which each axis, corresponding to R, G, or B, is from 0 to 255.

For your convenience, this release of the SDK includes sample BREW device files supporting

different color depths for various devices.

Running sample applications

Several sample applets and their sources are included with the SDK. It is helpful to run each

of the samples to get a better idea of the possibilities afforded by BREW. The sample

applications are found in the <BREW\Examples> directory. Sample applications are of two

types:

RGB (0x00, 0x80, 0x80) Dark Cyan

RGB (0x80, 0x80, 0x80) Dark Gray

RGB (0xc0, 0xc0, 0xc0) Light Gray

RGB (0xff, 0x00, 0x00) Red

RGB (0x00, 0xff, 0x00) Green

RGB (0xff, 0xff, 0x00) Yellow

RGB (0x00, 0x00, 0xff) Blue

RGB (0xff, 0x00, 0xff) Magenta

RGB (0x00, 0xff, 0xff) Cyan

RGB (0xff, 0xff, 0xff) White

Demonstration applications

These applications demonstrate the capabilities of various components of BREW, including the hello world application, games, scheduler, calculator, alarm clock, stopwatch, text memo, and MIDI-MP3 player. These applications are also intended to act as references and starting points for developing new applications.

Usage applications These applications demonstrate how to use BREW interfaces and APIs. The names of most of these applications begin with an I. For example, IMenuCtl application shows you how to use the BREW IMenuCtl interface to manage menus in a BREW application.

106


To run a sample application

1. Choose Start > Programs > BREW > BREW Emulator.

The Emulator opens with a list of the sample applications shown in the emulated

device’s window.

NOTE: As previously described, sample applications come in two types:

demonstration and usage. The type shown in the window depends on the selected

MIF directory. To change the directory, choose Tools > Settings, click Select MIF

Dir..., and change the MIF directory. Demonstration applications are stored in the

Apps directory, and Usage applications are stored in the Usage directory.

2. Choose the MIDI application.

You can choose applications using the keyboard left and right arrow keys. If the

selected device includes left and right arrow keys, you can also use those to scroll

through the applications.

3. When the selection is highlighted, click Select.

BREW loads the MIDI applet (that is, the MIDI applet DLL) and starts the

application. The MIDI application shows a screen similar to the following:

107


4. Using the arrow keys, choose a music file and click Select.

The following screen appears:

5. To play the sound clip, click Select.

6. To stop the applet or switch to a different applet, click End.

7. Now try the same application on a different device by selecting a device file using

File > Load Device.

8. To end the Emulator session, choose File > Exit.

Viewing and editing the application source code

After executing the sample applications and seeing how applets are organized and how they

work, you can explore the source code for the sample applications.

NOTE: You are advised to make a copy of the entire Examples directory before making any

change to the sample sources.

108


To view and edit the source code

1. If you are using Microsoft Visual Studio (Visual C++), the sample .dsw and .dsp files

have also been shipped with the SDK. Go to Visual C++ and open one of the

sample project workspaces (for example, HelloWorld.dsw). Alternatively, you can

double-click the HelloWorld.dsw file. This lists all the source and header files

belonging to the project.

NOTE: This release of the BREW SDK supports only the Microsoft Visual C++

development environment.

2. Make a small change to HelloWorld.c (for example, type a different text message)

and rebuild the application using the Build menu in your compiler.

3. Run the Emulator, choose the “Hello World App” applet, and run it to verify that your

change has taken effect.

Using the Application Manager

The <BREW\Examples\shared> directory contains images, MIDI files, and MP3 files used by

the Application Manager within the Emulator. This directory also contains a text file called

appinfo.txt. Whenever a change is made in the Application Manager, such as when a new

image is assigned to an application, the change is written to this file. When the Emulator is

started the next time, the system reads this file, along with the specified MIF directory, and

loads the correct configuration into the Application Manager.

When the Emulator is started, the Application Manager (AppManager) builds a main menu of

applets (with icons and titles of applets) and runs selected applets.

The Application Manager is a BREW application that serves as a starting point for browsing

and running the BREW applications available on the device. It has a simple GUI that shows

all the BREW applications present on the device. Using this GUI, you can navigate through

the different applications and run any of them.

NOTE: The <BREW\Examples\shared> directory contains images, MIDI files, and MP3 files

used by the Application Manager. You can add files to the shared directory to make them

available to the Application Manager.

109


The AppManager presents a set of small icons (soft key menu items) at the bottom of the

device screen, each corresponding to a BREW application. When the cursor (focus) is on the

soft key item, the large image for the corresponding application is shown on the main device

screen.

The last soft key menu is called Configure. This menu allows you to do the following:

• Control the sequence in which applications are shown by the Application Manager.

By default, the applications are shown in the order that their corresponding MIFs are

read by BREW. However, you can change the sequence as needed. For example,

if you always want Scheduler to be the first application, you can do it using the

Configure Menu.

• Associate image files with each application. When the cursor is on the soft key menu

item for an application, an image appears in the main screen. This image

supersedes the image (if any) contained within the MIF.

• Associate sound files (MIDI and MP3) with each application. When the cursor is on

the soft key menu item for an application, the corresponding sound file is played (if

the device supports sound files).

The Configure information is stored in a data file called appinfo.txt in the shared directory. The

AppManager reads these settings when the Emulator is restarted.

NOTE: The Application Manager included with the Emulator is not necessarily the same

Application Manager program used on each handset. OEMs may have their own customized

programs for managing applications.

To configure applets in the Emulator

1. If the Emulator is not already running, start it by clicking Start > Programs > BREW

> BREW Emulator.

2. Load the device for which you want to configure applets.

3. Use the left-arrow key until the Configure applet is highlighted, and click Select.

The Configure Menu screen appears.

110


4. Use the down-arrow key until the applet you want to configure is highlighted, and

click Select. For this example, choose Scheduler.

The Scheduler screen appears.

5. To change the image shown in this screen, press the right-arrow key until Image is

highlighted, and click Select.

You are presented with a list of images from which you can choose a new image.

6. Use the down-arrow key until the image you want to use is highlighted, and click

Select.

The new image replaces the old one, as shown below.

111


To configure an applet to play sound

1. Use the right-arrow key until Sound is highlighted, and click Select.

You are presented with a list of sound files.

2. Use the down-arrow key until the sound you want to use is highlighted, and click

Select.

3. When you are done configuring the applets, use the left-arrow key until Done is

highlighted, and click Select.

The Configure Menu screen reappears.

4. Use the right-arrow key until Done is highlighted, and click Select.

The first applet on your device appears.

112


Using speed emulation

When you run an application in the Emulator, it generally runs at a speed determined by your

PC’s processor. The speed at which the application runs after it is downloaded to the actual

device may differ significantly. And the speed that different devices run the same application

may also differ. The Speed Emulation feature allows the Emulator to run an application more

closely to the speed that it would run on the device.

The BREW SDK includes several device files already configured for speed emulation. These

are the devices in the <BREW/Devices> directory with SpeedEmu in the filename (for

example, LGE_CX-300L_SpeedEmu.qsc).

Configuring devices for speed emulation

If needed, you can configure other devices for speed emulation. This process involves the

following steps:

• Download the SpeedTune application from the BREW SDK to the device. Be sure

to include the MIF, MOD, BAR, SIG (device signature file), and testfile.rd files. The

MIF files for devices of various color depths are stored in the

<BREW/Examples/MIF/Apps> directory.

• Run the SpeedTune application on the device to generate a configuration file. This

file contains information about the device’s speed and is used to calculate the

device’s emulation speed.

• Upload the configuration file (brew_emu.dst) from the device to your PC. After

uploading the file, rename the file to something more meaningful.

NOTE: For information on downloading and uploading data to and from the device, see

the BREW AppLoader User Guide. This guide is included with the AppLoader

application that you can download from the BREW developer extranet site.

• Using the Configurator, configure the device so that it can be enabled for speed

emulation, and associate the uploaded configuration file with the device. See the

BREW Device Configurator Guide for more information.

• You can now enable the device for speed emulation in the Emulator.

113


• Optionally, you can perform the following two steps to ensure that the emulation

speed approximates the speed that your applications runs on the actual device.

- Load the device in the Emulator and tune the device’s speed parameters for

speed emulation. This process calculates the speed of emulation based on the

speed of your computer and the device.

- After the parameters have been tuned, you can enable the device for speed

emulation.

NOTE: For information on tuning speed parameters and enabling the device for speed

emulation in the Emulator, see Tuning speed emulation parameters and enabling the device

below.

Tuning speed emulation parameters and enabling the device

After you have associated the configuration file (.dst) with the device in the Configurator, you

can load the device in the Emulator. If you want to configure the emulation speed so that it

approximates the speed that your applications runs on the actual device, you can tune the

speed parameters.

NOTE: Tuning the emulation parameters is optional.

To tune speed parameters for a device and enable it for speed emulation

1. Load the device you configured for speed emulation into the Emulator.

2. Make sure the device is not enabled for speed emulation by clicking Tools > Speed Emulation. The Enable menu option must not have a check mark in front of it. If it

does, click Enable to disable speed emulation.

3. Choose Tools > Speed Emulation > Tune Parameters.

The Tune Parameters dialog box opens.

114


4. Click Run & Compute.

The DispSpeedTune application runs and generates the configuration file (.dst)

that contains the PC’s speed values.

5. After the Tune Parameters dialog box closes, you can enable speed emulation for

the device by clicking Tools > Speed Emulation > Enable.

At runtime in the Emulator, the speed value from the device is subtracted from the

speed of your PC processor to determine the emulation speed for the device.

Using TAPI emulation

TAPI (Telephone application programming interface) is used in the Emulator to emulate how

your applications handle the following three conditions:

• Calls incoming to BREW

• Outgoing calls from the application

• Incoming SMS messages

Handling calls incoming to BREW

You can emulate an incoming call initiated by a BREW application.

To emulate an incoming call

1. Choose Tools > TAPI Emulation.

The TAPI dialog box appears.

115


2. Click Start Call.

A Privacy Alert message appears, asking if you want to receive the call.

3. Click Yes to interrupt the currently-running application. There is a ten-second time-

out for you to respond; the default is No.

4. To end the call, click End Call.

In applications that use the EVT_APP_SUSPEND and EVT_APP_RESUME event

codes, the application resumes running at the interruption point. For all other

applications, the Application Manager shows the device’s initial screen.

Handling incoming SMS messages

The Emulator accommodates incoming IS-637 Short Message Service (SMS) messages.

These messages are then conditionally dispatched to applications. Applications that meet one

or more of the following conditions can receive SMS messages:

• Applications that have registered to receive specific IS-637 messages based upon

the teleservice ID of the message

• Applications that have registered to receive all IS-637 CMT 95 (4099) text

messages

• Any BREW applications to which a CMT 95 text message has been “directed.”

For more information on incoming SMS messages, see Monitoring incoming SMS messages

on page 39.

116


To emulate an incoming SMS message

1. Choose Tools > TAPI Emulation.


2. Click Send SMS.

.

The SMS dialog box appears.

3. Type the applet’s hex ClassID number and a text message you want sent to the

device.

4. Click Send.

The SMS dialog box closes and EVT_APP_MESSAGE with dwParam pointing to the user character string causes the message to appear in the device’s screen.

NOTE: In order for the message to be passed, the application must be in the

current applet directory and in the MIF path.

117


5. To terminate the message, click End Call.

In applications that use the EVT_APP_SUSPEND and EVT_APP_RESUME event codes, the application resumes running at the interruption point. For all other

applications, the Application Manager shows the device’s initial screen.

Handling calls outgoing from a BREW application

You can emulate an outgoing call initiated by the active BREW application using the ITapi

Usage applet. For your applications to have this capability, they must use the

ITAPI_MakeVoiceCall function. For more information, see the BREW API Reference.

To emulate an outgoing call

1. Use the left-arrow key until ITapi Usage is highlighted, then click Select.

NOTE: If you do not see this applet, choose Tools > Settings, and change the MIF

directory to Examples\MIF\Usage\256Color\.

The ITapi Functions screen appears.

2. Use the down-arrow key until 4. Make Voice Call is highlighted, then click Select.

118


A Privacy Alert message appears, asking if you want to allow the application to make the call.

3. Choose Yes to initiate the call.


.

4. To end the call, click End Call.

119

Extending BREW APIs

You can customize BREW API by providing BREW API Extensions that contain common

functionalities for use by many applications. For example, you can write an animation and

graphics extension for a set of games, or a sorting algorithm extension for a set of data

intensive applications.

Implementing the extensions is not much different than writing a BREW application. The

difference is that the extensions must expose their virtual function tables to the other external

classes.

NOTE: The examples in the following subsections are based on the Extension sample

application distributed with the BREW SDK.

Declaring the interface

The virtual function tables are exposed to third party developers through the interfaces in the

header files. The following example shows an extension called IExtensionCls:

QINTERFACE(IExtensionCls){

DECLARE_IBASE(IExtensionCls)int (*DrawSmiley)(IExtensionCls * po, AEEPoint ptCenter, int nRadius);int (*DrawHello)(IExtensionCls * po, AEEPoint ptXYOffset);

};

The previous code declares an interface of IExtensionCls through the macro QINTERFACE(),

and lists its member functions: DrawSmiley() and DrawHello(). These functions are accessed

through the following virtual table access macros:

#define IEXTCLS_AddRef(p) \GET_PVTBL(p,IExtensionCls)->AddRef(p)

#define IEXTCLS_Release(p) \GET_PVTBL(p,IExtensionCls)->Release(p)

#define IEXTCLS_DrawSmiley(p,ptC,nR) \GET_PVTBL(p,IExtensionCls)->DrawSmiley(p,ptC,nR)

#define IEXTCLS_DrawHello(p,ptC) \GET_PVTBL(p,IExtensionCls)->DrawHello(p,ptC)

120

Extending BREW APIs

Two extra member functions are exposed: AddRef() and Release(). They are derived from the

top-most parent class IBASE through the macro DECLARE_IBASE().

The AddRef() function needs to increment the internal reference count of the interface by one.

Following BREW policy, each module or class must perform its own reference count to

conserve memory. The Release() function must decrement the internal reference count by one

and check whether it has reached zero (0); if so, the function needs to free all the resources

allocated for the extension as well as for itself.

An additional macro, GET_PVTBL(), is used in the previous example to access the interface

functions through virtual function table pointers.

The C++ equivalent of the previous class declaration is shown in this example:

class IextensionCls : public IBase{

int DrawSmiley(IExtensionCls * po, AEEPoint ptCenter, int nRadius);int DrawHello(IExtensionCls * po, AEEPoint ptXYOffset);

}

NOTE: This C++ illustration is for explanatory purposes only. You cannot use C++ yet since

there are issues with the ARM Compiler. We are looking into these issues and will soon make

this feature available.

Defining the class

The interface declared in the previous section must have an actual content, which physically

defines the behavior of the module. Continuing with the previous example, the following code

is a simple class definition:

typedef struct _ExtensionCls{

// Declare our VTable// by doing so, we have placed function pointers// in the beginning of this structureDECLARE_VTBL(IExtensionCls)

// Class member variablesuint32 m_nRefs; // References to usIShell * m_pIShell; // copy of Shell pointerIDisplay * m_pIDisplay; // Display interface pointerIModule * m_pIModule; // IModule interface pointer

} ExtensionCls;

121

Extending BREW APIs

Inside the class, the macro DECLARE_VTBL() inserts the virtual table into the class definition.

NOTE: This virtual table declaration must be the first line inside the class.

After the virtual table declaration, you can enumerate all of the member variables in any order.

A mandatory member variable is m_rRefs, which keeps count of all the modules that have

references to the extensions. This variable makes possible the functions AddRef() and

Release(), which were discussed in the previous section.

Defining the class functions

For the example extension, four functions are declared from the interface: AddRef(),

Release(), DrawSmiley(), and DrawHello(). In addition to these functions, there must be one

more function: AEEClsCreateInstance().

The functions AddRef() and Release() are responsible for module reference counting and

cleaning up the modules as described earlier. DrawSmiley() and DrawHello() perform the

intended functionality of the extension.

The AEEClsCreateInstance() function must perform several tasks that regular BREW modules

usually don’t perform. Instead of calling AEEApplet_New() to create, it must call its own new-

operator. In this example, we’ll call it ExtensionCls_New() with the following signature:

int ExtensionCls_New(int16 nSize, IShell *pIShell, IModule* pIModule, IModule ** ppMod);

Inside this function, the following actions must occur:

• allocate the memory

• initialize the virtual table

• initialize the class members

• initialize any other codes

These tasks are described below.

122

Extending BREW APIs

Memory allocation Memory must be allocated for the class, including all of the member variable instances, and the virtual function table, as shown in the following example:

VTBL(IExtensionCls) * modFuncs;if(!ppMod || !pIShell || !pIModule) return EFAILED;*ppMod = NULL;

// Allocate memory for the ExtensionCls objectif(nSize < sizeof(ExtensionCls))

nSize += sizeof(ExtensionCls);if((pMe = (ExtensionCls *)MALLOC(nSize +

sizeof(VTBL(IExtensionCls)))) == NULL ) return ENOMEMORY;

Virtual Function Table Initialization

After the memory block for the class and virtual function table is allocated, the virtual function table must be initialized to point to the right functions, as shown in the following example:

modFuncs = (IExtensionClsVtbl *)((byte *)pMe + nSize);//Initialize individual entries in the VTBLmodFuncs->AddRef = ExtensionCls_AddRef;modFuncs->Release= ExtensionCls_Release;modFuncs->DrawSmiley= ExtensionCls_DrawSmiley;modFuncs->DrawHello= ExtensionCls_DrawHello;

// initialize the vtableINIT_VTBL(pMe, IModule, *modFuncs);

NOTE: This step first initializes each individual entry in the virtual function table, and then it initializes the table itself.

Class MemberInitialization

After the virtual function table has been initialized, the next step is to initialize each class member, as shown in the following example:

// initialize the data memberspMe->m_nRefs = 1;pMe->m_pIShell = pIShell;pMe->m_pIModule = pIModule;

NOTE: It is important to initialize m_nRefs, the reference counter, to one. At the time of creation, the reference count is one.

123

Extending BREW APIs

Other initialization Finally, any other initialization codes must come next before returning from the function, as shown in the following example:

// Add References and get IDisplayISHELL_AddRef(pIShell);IMODULE_AddRef(pIModule);if(ISHELL_CreateInstance(pIShell, AEECLSID_DISPLAY, (void **)&pMe->m_pIDisplay) = SUCCESS) return EFAILED;

// Set the pointer in the parameter*ppMod = (IModule*)pMe;return AEE_SUCCESS;

NOTE: In all cases, the function must increment the ISHELL and IMODULE reference counts by one. This is reversed in the Release function where ISHELL_Release() and IMODULE_Release() are called to bring the reference counts back to the original number.

The C++ equivalent of the above class implementation is:

class ExtensionCls : public IextensionCls{

// Class member variablesuint32 m_nRefs; // References to usIShell * m_pIShell; // copy of Shell

pointerIDisplay * m_pIDisplay; // Display interface

pointerIModule * m_pIModule; // IModule interface

pointer}

NOTE: This C++ illustration is for explanatory purposes only. You cannot use C++ yet since there are issues with the ARM Compiler. We are looking into these issues and will soon make this feature available.

124

Extending BREW APIs

Extension Usage

After all the work is done, another application can create an instance of the extension through

the ISHELL_CreateInstance() call. After this call is successfully completed, each function is

accessible through the macros defined in the header file. It is very important that the extension

be cleaned up by calling the Release function. The following example shows an extension

being called and released:

if(ISHELL_CreateInstance(pMe->m_pIShell, AEECLSID_EXTENSION_CLS, (void **)&pExtCls))

return FALSE;IEXTCLS_DrawSmiley(pExtCls, ptSmile, 15);IEXTCLS_DrawHello(pExtCls,ptHello);IDISPLAY_Update(pMe->m_pIDisplay);IEXTCLS_Release(pExtCls);

The following diagram summarizes this applet:

Applet

IEXTCLS_AddRef

IEXTCLS_Release

IEXTCLS_DrawSmiley

IEXTCLS_DrawHello

Macros

AddRef

Release

DrawSmiley

DrawHello

IExtensionCls VTBL

ExtensionCls_AddRef() { … }




125

Using Visual Studio Add-Ins

Microsoft Visual Studio, also known as the Integrated Development Environment (IDE), is a

system requirement that must already be loaded on your PC before you can install the BREW

SDK. If you install the SDK before installing Visual Studio, you must reload the SDK for these

add-in to take effect.

The SDK includes free add-ins that automate some of the tasks you must perform in Visual

Studio to develop BREW applications.

BREW Application Wizard add-in

If you use the source code from the sample applications included with the BREW SDK as the

basis for your own applications, you must be very careful to avoid making errors while setting

up your BREW project. The BREW Application Wizard, subsequently referred to as the

AppWizard, can guide you through the often time-consuming tasks involved in creating a

BREW application project, including the creation of the Windows project workspace. It can

also help you avoid any mistakes that can occur when you manually change the sample

application code for your own applications. The AppWizard automatically generates the

project workspace and all the files you’ll need to start creating BREW applications.

In addition to saving you time and effort, the files you create using the AppWizard are highly

mobile. You can move your project from one location on your computer to another without

having to modify the project file (DSP) or the paths to the project’s INCLUDE statements.

To create an application project with the AppWizard

1. Start Microsoft Visual Studio, and choose File > New.

The New dialog box opens.

2. Click the Projects tab.

The following fields are shown.

126


3. Select BREW Application Wizard and make the following entries:

a. In Project name, enter a name for your new BREW project.

b. In Location, enter a new path to the directory where you want to store the files

for the project.

4. Click OK.

The AppWizard opens the first of two dialog boxes.

127


5. Check the interfaces you want to include in your application. When the project file

is generated, the header files for the selected interfaces are included in your

project’s main source file.

6. Click Next.

The second AppWizard dialog box opens.

128


7. Do one of the following:

a. To create the MIF for your project at a later time, proceed to step 8.

b. To create a MIF for the project right now, click MIF Editor. See the BREW MIF

Editor Guide for instructions on creating the MIF.

When you have finished creating the MIF, close the MIF Editor window.

8. In the second AppWizard dialog box, click Finish.

The New Project Information dialog box opens.

129


9. When you have finished viewing the new project information, click OK.

The Microsoft Visual C++ window reopens with your new BREW application project

loaded in the workspace.

130


The AppWizard has created the following files:

• Project file (application.dsp)

• Workspace file (application.dsw)

• Application source file (application.c)

NOTE: Two other files required by BREW applications, AEEAppGen.c and

AEEModGen.c, are included with the BREW SDK in the BREW/Src directory.

These two files are automatically included in your new BREW project.

10. You can now compile your project. However, if you have not already acquired a

BREW ClassID (BID) from the BREW web site and used it to create a MIF for the

project, one warning and one error will be generated. These disappear after you

create the MIF. See Sample 1: "Hello World" on page 66 for information on

including the BID.

NOTE: The AEE_SIMULATOR preprocessor is required by all applications intended to run on

the SDK in the Windows environment. If you created your application using the Application

Wizard, this preprocessor has already been defined for the project.

Automated ARM compiling add-in

When you have already tested a BREW application in the Emulator and are ready to port it to

an actual device, you need to create a makefile (MAK) that builds the BREW application for

the actual device using the ARM compiler (version 1.0 or higher). Generally, the makefile is

used from a command line to perform build and build clean operations. The automated ARM

compiling add-in allows you to quickly perform these time-consuming tasks in a matter of

seconds. Additionally, the add-in automates the task of finding and fixing errors during the

compilation.

NOTE: The ARM compiling add-in causes three new buttons (Generate ARM Makefile, BREW

MIF Editor, and BREW Resource Editor) to appear on the Visual Studio toolbar. Clicking these

buttons opens the associated applications. If these toolbar buttons are not on the toolbar when

you open Visual Studio, follow the procedure in step 2 below.

131


To create a makefile for your application

1. Load your application in a Visual Studio workspace.

2. If the new toolbar buttons do not appear on the Visual Studio toolbar), do the

following:

a. Choose Tools > Customize.

The Customize dialog box opens.

b. Click the Add-ins and Macro Files tab.

c. Select ARMMakeBREWApp.DSAddIn.1.

d. Click Close.

The new toolbar buttons appear on the Visual Studio toolbar.

3. Click the Generate ARM Makefile toolbar button to generate the makefile.

A message box appears informing you that the makefile has been generated.

To compile your application using the makefile

1. If you have a makefile that has already been used in an application build, and you

want to clean out all object files before compiling, see the next procedure, To clean

a makefile.

2. Choose Tools > arm make.

The output window opens and shows the files created from the compilation.

NOTE: If you choose arm make without having first created a makefile, the output

window displays: Fatal Error: Makefile Not Found. See the previous

procedure, To create a makefile for your application, for instructions.

To clean a makefile

1. If you have not done so already, load your application in a Visual Studio workspace.

2. Choose Tools > arm clean.

Old object files are removed from the makefile, and the message panel shows the

files that were removed, such as the following:

132


CLEANdel /f AEEAppGen.o AEEModGen.o helloworld.odel /f helloworld.elfdel /f helloworld.mod.

NOTE: If you choose arm clean without having first created a makefile, the output

window shows: Fatal Error: Makefile Not Found. See To create a makefile

for your application for instructions.

To find and fix compilation errors

1. If an error, such as Serious error: C2947E: Illegal types for operands:

'unary *', appears in the message window following a compile, double-click the

error line in the output window.

As shown below, a small, blue line to the left of the code points to the line of code

at which the error occurred.

2. If other errors are shown in the output window, repeat this process until all errors

have been corrected, and perform the compile again.

133

Appendix A: SDK SoftwareBackward Compatibility

This appendix describes SDK software compatibility issues you may need to be aware of if you

have downloaded multiple versions of the SDK software.

NOTE: For more information and late-breaking issues that may have arisen since this

document was updated, click Start > Programs > BREW > BREW ReadMe.

BREW Release

Backward Compatible With Comments

1.1.0.x 1.0.1.x1.0.2.x

1) Possible compilation errors can occur for applications written in the 1.0.1 release that use the AEEClsCreateInstance() function with IApplet** as the last parameter, instead of void**. See the ReadMe file for details and a procedure for fixing this problem.

2) If you delete a makefile generated in a prior release and attempt to regenerate the makefile using the Application Wizard in MS VC++, the environment variable inserted into the makefile does not point to AEEModGen or AEEAppGen in the old release, but in the latest one. You need to run the BREWDIR.bat file from the <BREW/Bin> directory in the BREW SDK release for which you want to use the AEEModGen or AEEAppGen files. You can then run the makefile generator in MS VC++.

3) Setting a -ve time out timer using ISHELL_SetTimer() returns SUCCESS and sets a DISPATCH_THROTTLE_TIME ms timer. In the 1.0.1 release, setting a -ve time-out timer using ISHELL_SetTimer() returned EINVALIDTIME.

1.0.2.x 1.0.1.x Possible compilation errors can occur for applications written in the 1.0.1 release that use the AEEClsCreateInstance() function with IApplet** as the last parameter, instead of void**. See the ReadMe file for details and a procedure for fixing this problem.

134

Appendix A: SDK Software Backward Compatibility

1.0.1.x None None

1.0.0.x None None

BREW Release

Backward Compatible With Comments

135

Appendix B: Event Codes andKey Codes

The following tables list the event codes and key codes supported by BREW.

Key Codes are received with EVT_KEY, EVT_KEY_PRESS, EVT_KEY_RELEASE, and

EVT_KEY_HELD events.

Event codes

Event code Description Parameters

EVT_APP_START Application start. wParam = 0, dwParam = 0.

EVT_APP_STOP Application stop. wParam = 0, dwParam = 0.

EVT_APP_SUSPEND Application suspend. wParam = 0, dwParam = 0.

EVT_APP_RESUME Application resume. wParam = 0, dwParam = 0.

EVT_APP_CONFIG Alternate application start. Configuration screen shown.

wParam = 0, dwParam = 0.

EVT_APP_HIDDEN_CONFIG

Alternate application start. Configuration screen hidden.


EVT_APP_BROWSE_URL Not supported.

EVT_APP_BROWSE_FILE Not supported.

EVT_KEY Key handling event. wParam = key code (see Key codes table), dwParam = OEM-specific.

EVT_KEY_PRESS Keypress event. wParam = key code (see Key codes table), dwParam = OEM-specific.

EVT_KEY_RELEASE Key release event. wParam = key code (see Key codes table), dwParam = OEM-specific.

136


EVT_KEY_HELD Key held event. The hold time is device-specific. Not supported in Emulator.

wParam = key code (see Key codes table), dwParam = OEM-specific.

EVT_COMMAND Application custom controls event.

wParam = user command ID, dwParam = user data.

EVT_CTL_TAB Application tab event. wParam = 0-left, 1-right, dwParam = pointer to the control.

EVT_CTL_SET_TITLE Set control title event. wParam = ID, dwParam = if ID is not zero, then resource file, else text.

EVT_CTL_SET_TEXT Set text control event. wParam = ID, dwParam = if ID is not zero, then resource file, else text.

EVT_CTL_ADD_ITEM Message interface to add item. wParam = 0, dwParam = CtlAddItem *.

EVT_CTL_CHANGING Change control event. wParam = 0, dwParam = CtlValChange*.

EVT_CTL_MENU_OPEN Sent by ITextCtl before menu is activated.

wParam = 0, dwParam =IMenuCtl *.

EVT_DIALOG_INIT Dialog event: Controls created. wParam = Dialog ID, dwParam = IDialog *.

EVT_DIALOG_START Dialog event: Dialog opening. wParam = DialogID, dwParam = IDialog *.

EVT_DIALOG_END Dialog event: Dialog completed normally.

wParam = DialogID, dwParam = IDialog *.

EVT_COPYRIGHT_END Dialog event: Copyright dialog ended.

wParam = DialogID, dwParam = IDialog *.

EVT_ALARM Alarm event. wParam = Alarm Code, dwParam = 0.

EVT_NOTIFY BREW-generated notification or application-registered notification event.

wParam = 0, dwParam = AEENotify *.

EVT_BUSY Sent to application to determine if the application can be suspended or stopped. Application must return TRUE if it does not want to be suspended or stopped. Typically, applications return FALSE.



137


Key codes

EVT_FLIP Device-specific event: Sent to application when flip-type (clam-shell) device is opened or closed.

wParam = TRUE if open, FALSE if closed; dwParam = 0.

EVT_LOCKED Device-specific event: Sent to application when device user interface is locked.

wParam = TRUE if locked, FALSE otherwise; dwParam = 0.

EVT_KEYGUARD Device-specific event: Sent to application when device keypad is locked.

wParam: TRUE if keyguard is on, FALSE otherwise; dwParam = 0.

EVT_USER Start of application/user-defined events.

Private to application.

Key code Value Description

AVK_UNDEFINED 0xE010 Invalid Key Code

AVK_0 0xE020 0 key

AVK_1 0xE021 1 key

AVK_2 0xE022 2 key

AVK_3 0xE023 3 key

AVK_4 0xE024 4 key

AVK_5 0xE025 5 key

AVK_6 0xE026 6 key

AVK_7 0xE027 7 key

AVK_8 0xE028 8 key

AVK_9 0xE029 9 key

AVK_ASTERISK 0xE02a * Key

AVK_NUMBER_SIGN 0xE02b # key

AVK_POWER 0xE02c Power key

AVK_SEND 0xE02d Send key

AVK_END 0xE02e End key

AVK_CLEAR 0xE02f Clear key

AVK_UP 0xE030 Up key


138


AVK_DOWN 0xE031 Down key

AVK_LEFT 0xE032 Left key

AVK_RIGHT 0xE033 Right key

AVK_SELECT 0xE034 Select key

AVK_SOFT1 0xE035 Soft key 1




AVK_FUNCTION1 0xE039 Function key 1

AVK_FUNCTION2 0xE03a Function key 2

AVK_FUNCTION3 0xE03b Function key 3

AVK_FUNCTION 0xE03c Function Key

AVK_MENU 0xE03d Menu key

AVK_INFO 0xE03e Info key

AVK_SHIFT 0xE03f Shift key

AVK_MESSAGE 0xE040 Message key

AVK_MUTE 0xE041 Mute key

AVK_STORE 0xE042 Store key

AVK_RECALL 0xE043 Recall key

AVK_PUNC1 0xE044 Punctuation key 1

AVK_PUNC2 0xE045 Punctuation key 2

AVK_VOLUME_UP 0xE046 Volume up key

AVK_VOLUME_DOWN 0xE047 Volume down key

AVK_WEB_ACCESS 0xE048 Web access key

AVK_VOICE_MEMO 0xE049 Voice memo key

AVK_SPEAKER 0xE04a Speaker key

AVL_LAST 0xE04c Not used

Key code Value Description

139

Appendix C: Problems andWarning Messages

This appendix describes problems and error messages you might encounter while working in

the BREW SDK, along with probable causes and suggestions for solving the problems. The

appendix is divided into subsections, each describing troubleshooting for the various

components of the SDK, as shown in the following table.

For these problems or messages See

Emulator problems page 140

Emulator messages page 141

Applet-specific messages page 142

Configurator problems page 143

Configurator messages page 144

MIF Editor messages page 146

Resource Editor messages page 147

140


Emulator problems

The following problems are specific to the Emulator.

Problem Cause Solution

The device image is shown, but the device screen is blank.

The MIF directory is wrong. From Tools > Settings or from File > Change MIF Dir, change the MIF directory.

The Emulator window is blank after startup or after changing settings or changing device.

Device file is wrong. Possible causes for a wrong device file include:

• The screen object doesn't exist.

• The screen is too small or too big.

• The color depth is not one of 1, 2, 4, 8.

From Tools > Settings or from File > Load Device, change the device file.

While trying to play a MIDI or MP3 file, the file fails to run.

Possible causes include:

• The file is not present.

• The file is not MIDI or MP3 format.

• The operating system version is lower than Windows NT 4.0-Service Pack 3 or Windows 2000-Service Pack 2.

• Multimedia capabilities are not present on the computer.

• Multimedia software components are not present in the operating system.

First, make sure the file is present and is of MIDI or MP3 format.

Next, make sure the operating system is at least Windows NT 4.0-Service Pack 3 or Windows 2000-Service Pack 2.

Finally, make sure the computer has hardware and software multimedia capabilities. To verify this, download and install Windows Media Player (version 6.4 and above for NT, or version 7.0 and above for Windows 2000) from the Microsoft web site, then open and play Sample.mid and Sample.mp3 under the <BREW\Bin\DataFiles> directory.

141


Emulator messages

The following messages are Emulator-specific.

Message Cause Solution

Failed to initialize BREW. The heap size ...

(displayed when loading a device in the Emulator)

The heap size specified in the device file is smaller than what BREW requires.

Edit the device file using the Configurator. Click Details in Attribute View. The Device Attributes dialog box opens. Increase the heap size, click OK, save the device, and reopen in the Emulator.

Failed to initialize the device


Device resource file (.qsc file) is either corrupt or contains invalid data.

First, make sure the device file is in the same directory as the device resource file. If it is, open the device resource file using the Configurator. The Configurator then fails to read the file and returns an error number.

Failed to write to the settings file.

(displayed in Emulator after clicking OK in Settings dialog box)

The BREW_Emu.dat file may be read-only.

Make sure the BREW_Emu.dat file is not read-only. The BREW_Emu.dat file is under Brew\Bin directory.

There is no real size screen info

(displayed when you choose View > Real Size Screen in the Emulator)

Either the screen width or height is 0 (zero).

Edit the device file using the Configurator. Select the screen and update the screen dimension, and then save the device and reopen it in the Emulator.

Windows has not enough memory...


The heap size specified in the device file is bigger than what Windows can allocate.

Change to another device that has a smaller heap size, decrease heap size using the Configurator, or close some Windows applications.

142


Applet-specific messages

The following messages are BREW applet-specific. These messages are displayed by IShell

on the device screen.


Digital service is required to use this feature.

The device does not have digital service.

Ensure that the device is in a digital coverage area.

Insufficient Memory There was not sufficient memory to load and execute the application.

On the SDK, increase the memory size from the device configuration file.

On the device, restart the phone.

Module failed to free all memory.

The application did not free all the memory it allocated during execution.

Ensure the application does not have memory leaks. You can run the application through a standard tool such as "Purify" to catch the exact locations of memory leaks. Before running "Purify," make sure to change the device configuration to use "Windows Heap."

Security Violation! The signature verification process failed. This process is carried out after the application is downloaded to the device and before it is executed.

Download the application to the device again.

This application has been unloaded to save memory. You must download a new version.

The applet subdirectory or the applet module (.mod on the device and .DLL on the SDK) could not be found.

On the SDK, ensure that the applet subdirectory exists and has the same name as the MIF. Also, ensure that the applet subdirectory contains the applet DLL.

On the device, either download the application again, or ensure that the applet subdirectory and applet module exist.

143


Configurator problems

This application has expired.

The allowed duration of use for the application has expired.

Download the application to the device again.

Unable to start application.

or

Unknown Error

The application load procedure failed due to initialization errors. This can occur if one or more operations failed using the AEEClsCreateInstance() function or during APP_START event processing.

Debug the application to check which of the initialization operations (mainly in CreateInstance() and handling the APP_START event) failed.

Problem Cause Solution

When you select an object Type of Screen or Key, you are informed that the device object cannot be created.

There are no more free virtual codes available. You have created more objects than the total number of free virtual codes available.

Make sure there are enough virtual codes available for the created objects. Locate and delete UNDEFINED objects in the Created Device Objects list. See the BREW Device Configurator Guide for details.

In the device pane, the device image appears as black and white.

The Windows Color Palette or the Number Of Colors field is set to less than or equal to 256 colors.

Choose Control Panel > Display > Settings. Set the Color Palette or Number Of Colors to more than 256 colors.

The device pane is blank and you cannot proceed further.

The main image file is blank, or you did not specify an image file when creating a new project.

See if the image file is blank.

Specify the correct image file when choosing a new file.

You cannot save the device (or resource) file.

There is a sharing violation or other file permission problems.

Check if the device file is used by some other application. Also check for its file permissions.

While you are creating an object in the device pane, the rectangle disappears.

The object you are trying to create intersects or overlaps another object’s boundary rectangle.

Create objects that are within the device boundary and that are not intersecting or overlapping with any other objects.


144


Configurator messages


Coordinates out of device boundary or intersecting/over-lapping with other objects. . .

You entered a value in the Coordinates fields and one of the following problems exists:

• The coordinates of the object rectangle are beyond the device boundary. The coordinates of a device object must always lie within the device boundary.

• The device object intersects or overlaps with some other device object.

In the device pane, select the object rectangle and use the sizing handles to adjust it. If you need to add a value manually, adjust the Coordinates fields in the attribute pane.

Error adding primary code

You tried to assign the primary code for a key object and there are no more free virtual codes available. You have created more objects than the total number of free virtual codes available.

Always make sure that there are enough virtual codes available for the created objects. Locate UNDEFINED objects (use the Created Device Objects list) and delete them. See the BREW Device Configurator Guide for details.

Error adding virtual code

You tried to add an overload code for a key object when there may be too many overload codes. The Configurator allows only five overload codes per key object.

Do not assign more than five overload codes per key object.

Fatal: Language type load error

You tried to open the Device Attributes dialog box.

There is a problem with the binary. Contact BREW technical support.

145


Pushed Image file not found, wrong format or same as Main Image file

You entered a pushed image file that does not exist, is corrupted, or is the same as the main image file.

NOTE: The Configurator reads and validates the pushed image file.

Enter the correct image filename, or leave the field blank (the pushed image file is optional).

Resource File read error: <cause>

You tried to open a .qsc file or load a new image file and one of the following problems exists:

• Configurator cannot find the main image file.

• Main image file is invalid.

• One or more device objects are out of the main image boundary.

• Configurator encountered a fatal Windows GDI resource allocation error.

• Configurator could not open the device (or resource) file.

• Configurator found an invalid keyword in the device file.

• Configurator found an entry with insufficient parameters in the device file.

• Error setting locale.

• Unknown error.

Make sure the main image file is in the same directory as the resource, and that it is a valid image.

For all other errors, please contact BREW technical support.

We recommend that you modify the device file using the Configurator, not an editor.

The font that you have selected is System Font. It does not have distinct Normal and Bold characteristics. Both Normal and Bold will appear similar. Do you want to continue with this font?

You selected the system font in the Font dialog box.

Select another font; the system font does not appear properly in the Emulator.


146


MIF Editor messages


A required field is empty. Please enter a 32-bit hexadecimal number.

You left one or more required fields empty.

Enter a number in the required fields.

A required field was left empty. Please enter a string.

You left one or more required text fields empty.

Enter text in the required fields.

Are you sure you want to generate a ClassID locally?

You attempted to use Local ClassIDs when submitting an application for BREW certification.

Use local ClassIDs for testing only. Applications submitted using a local ClassID will not pass BREW certification.

Checking "Show on Config Menu" and/or "Show on Hidden Config Menu" requires a Menu String.

In the Advanced Applet dialog box, you selected Show on Config Menu or Show on Hidden Config Menu, without specifying a Menu String.

If you choose Show on Config Menu or Show on Hidden Config Menu, specify a Menu String.

"Menu String" needs to be associated with "Show on Config Menu" and/or "Show on Hidden Config Menu". Please check the applicable.

In the Advanced Applet dialog box, you entered a menu string, but did not choose Show on Config Menu and/or Show on Hidden Config Menu.

If you enter a menu string, you must choose Show on Config Menu and/or Show on Hidden Config Menu.

The file <name> does not exist.

The filename you entered cannot be found.

Verify that the file exists and that you spelled the name correctly.

The MIF file you attempted to open was produced by an incompatible version of the MIF Editor and cannot be opened.

Version incompatibility. See Appendix A: SDK Software Backward Compatibility on page 133 for a list of backward-compatible versions and issues.

The value cannot be zero. Please enter a non-zero 32-bit hexadecimal number.

You entered zero in a field that must be non-zero.

Enter a value, other than 0 (zero).

147


Resource Editor messages

You must either specify a system class or a custom class notification type.

You added a new notification without specifying a custom or system class notification.

Specify either a custom or system class notification when adding a new notification.

You must have at least one class or applet defined.

A MIF must contain at least one applet to be saved.

Specify at least one applet or class in the MIF and try saving it again.


An error occurred while trying to save the resource file ....

This error can occur if the Resource Editor was unable to open a BRI file, or if the Resource Editor could not save a resource file for one or more of the following reasons:

• The file is read-only.

• Not enough disk space is available to create the file.

• There is a sharing problem or other file permission problems.

• An unknown error occurred.

BRI open error:

• If the BRI file is corrupt, re-create the file.

• Make sure the file is not read-only.

• Ensure that your PC has sufficient disk space.

• Check the file’s permission and sharing settings.

Save error:

• Make sure the file is in a format recognized by the Resource Editor.

• Check the file’s permission and sharing settings.

For all other errors, please contact BREW technical support.

Could not open the "..." file. Make sure it is not marked as Read-Only.

The file could not be opened. If the file is read-only, remove that attribute so that it can be opened successfully.


148


No resources to build. The compiled resource file and header files will not be created.

There are no resources to compile.

To create a valid BAR (output) file, you must specify at least one resource in the resource file.

The control ID in which you wish to set initial focus is not valid for this dialog. Please choose a control ID that exists within this dialog box.

You are attempting to set initial focus to a control in a dialog that does not exist in that dialog.

Make sure that the specified control ID is shown in the Dialog Controls list.

The control resource ID you specified is already used by another control. Please choose a unique control resource ID.

The ID you specified for the resource type already exists.

Choose a unique ID. By default the Resource Editor automatically generates the ID.

The dialog resource ID you specified is already used by another dialog. Please choose a unique dialog resource ID.



The file does not contain any extension and hence the Image Type (MIME Type) cannot be determined.

The extension is missing on the image file. The image type cannot be determined, because the image type (MIME type) is based on the extension.

Make sure the image file has the correct extension. For example, a bitmap file should have a .bmp extension.

The image resource ID you specified is already used by another image. Please choose a unique image resource ID.




149


The image you have selected is 80 pixels wide, 80 pixels tall, and has 8 bits/pixel. Typically, image resources are less than 150 pixels wide, 150 pixels tall, and have 1 bit(s)/pixel.

This warning describes the details of the selected image and identifies the dimensions of a typical image resource.

If an image size is larger that the screen size on the phone, the image is clipped.

Change the size of the selected image or select another image that is within the size restriction.

The list item resource ID you specified is already used by another list item. Please choose a unique list item resource ID.



The resource file that you are opening is from a previous version of the application. The file will automatically be upgraded to the format of the current version when it is saved. If you do not wish to upgrade the format of the file then select File->Save As and save the file as a different filename.

BREW version incompatibility. See Appendix A: SDK Software Backward Compatibility on page 133 for version compatibility issues.

The resource name you specified is already used by another resource. Please choose a unique resource name.



The string resource ID you specified is already used by another string. Please choose a unique string resource ID.




150


The version of the file you are opening was created with a version of the application that is not compatible with this version. You will need to obtain an updated version of this application in order to open this file.

BREW version incompatibility. See Appendix A: SDK Software Backward Compatibility on page 133 for version compatibility issues.

You must enter a resource name for this dialog.

You have not entered a resource name for the dialog resource.

Enter a valid resource name.

You must enter a resource name for this image.

You have not entered a resource name for the image resource.

Enter the requested resource name.

You must enter a resource name for this list item.

You have not entered a resource name for the list item resource.


You must enter a resource name for this string.

You have not entered a resource name for the string resource.


You must enter a string for this resource ID.

You have not entered a string for this string resource

Enter a valid string.

You must enter an ID for this dialog resource.

You have not entered an ID number for the dialog resource.

Enter a valid ID number.

You must enter an ID for this image resource.

You have not entered an ID for the image resource.

Enter the requested ID number.

You must enter an ID for this string resource.

You have not entered an ID for the string resource.

Enter the requested ID number.


151


You must have at least one string resource for your dialog box(es)

There are no string resources in your resource file.

You must specify at least one string per dialog.

You must specify a path\filename of a valid image.

You entered an invalid path or filename for the image file.

Enter a valid path and filename.


152

Index

AAcronyms used in this manual, 11Add-ins

Application Wizard, 125automated ARM compiling, 130Visual Studio, 125

AEEheaders, 33IBase class, 49model, 29

APIextensions, 119interfaces, 30

Appletschanging directory, 100ClassIDs for, 36configuring in the Emulator, 109creating, 37directory on SDK, 23events passed to, 50overview, 32processing events for, 37resuming, 38suspending, 38

Applicationcertifying, 30creating new, 40developing with BREW, 28source code, viewing and editing, 107

Application Manager, configuring applets with, 108

Application Wizard add-indescription of, 125files created with, 130

Authentication, developer, 30Automated ARM compiling, 130

BBackward compatibility of SDK software, 133Bin directory, 20Bitmaps directory, 20

CCase sensitivity of paths on PC and device, 25Changing

applet directory, 100application source code, 107MIF directory, 101

Classcreating, 36defining, 120methods of defining, 121

ClassIDsapplet, 36assigning to applets or classes, 34interface, 34

Cleaning a make file, 131Color support in the BREW Emulator, 104Compilation errors, finding and fixing, 132Controls

dialog, 92using, 89

Conventions, documentation, 9Creating

applets, 37applications, 40classes, 36dialogs, 89, 91instances, 36make file for application, 131

DDatabase management sample application, 85Defining

class methods, 121classes, 120

Deviceconfiguring for speed emulation, 112directory, 20files, 20selecting, 100

Device Attributes dialog box, error on opening, 144

Device Configurator, description of, 17Device file

cannot save, 143error on opening, 145

Index

153

Device paneblack and white image appears, 143image is blank, 143

Dialogsapplication example, 93controls, 92creating manually, 91creating with Resource Editor, 89events, 92terminating, 93using, 89

Directed SMS messages, 39Directory structure, 20DLLs, BREW and OEM, 17Docs directory, 20Dynamic modules, 49

EEmbedded file system, 53Emulator

changing backlight, 104color, 104description of, 17, 97menus, 99setting screen size, 102starting, 97

Eventcodes, 135handling, 51passed to an applet, 50processing, 37

Examples directory, 20Extending APIs, 119

FFeatures, requesting new, 15File management sample application, 83File system, embedded, 53Filenames, entering on PC and device, 25Floating-point operations, 41Font, error when selecting, 145

HHeader files, 17Headers, AEE, 33Hello World sample application, 66

IIApplet interface, 50IBase interface, 49

Image file, error when loading, 145IModule interface, 49Inc directory, 20Incoming SMS messages, monitoring, 39, 115Initializing virtual function table, 122Installing the SDK, 16Instances, creating, 36Interfaces

ClassIDs, 34IApplet, 50IBase, 49IModule, 49IShell, 48structure, 30using, 30

KKey codes, 137Key object errors, 144Keypress events, 51

LLarge font, error when selecting, 145Links, using, 10

MMake file

cleaning, 131creating for application, 131

Memory allocation, 122Menus of BREW Emulator, 99MIF directory

changing, 101description, 23

MIF Editor, description of, 17MIFs, overview, 34Module structure, 30Monitoring incoming SMS messages, 39, 115

NNormal font, error when selecting, 145

OObject technologies, 29Online manuals, using, 9Output window, 102Overload code, error assigning a code, 144

Index

154

PPaths, entering on PC and device, 25Primary code, error assigning a code, 144Printing in online manuals, 10Processing applet events, 37Programming concepts, 32Project, creating with Application Wizard, 125Pushed image file, error when loading, 145

RReadme directory, 20Requesting new BREW features, 15Resource directory, 24Resource Editor, description of, 17Resuming an applet, 38

SSample application

code for general applications, 54code for incoming SMS messages, 40Hello World, 66resource management, 71running, 105shipped with SDK, 22using databases, 85using files, 83using sockets, 88using timers and alarms, 79

Screen objecterror when creating, 143, 144rectangle disappears, 143

Screen size, setting in Emulator, 102Searching within online manuals, 10Selecting a device, 100Shared modules, 28Shell services, 48SMS messages

directed, 39monitoring, 39, 115sample code, 40

Socket sample application, 88Software, backward compatibility, 133Sound files, 109Speed emulation

configuring devices for, 112enabling, 103

SpeedTune, downloading and running, 112Src directory, 20Starting the BREW Emulator, 97Static modules, 49Suspending an applet, 38

Systemrequirements, 16resources, language-specific, 41startup, 33

TTAPI emulation

calls outgoing from a BREW application, 117description, 103incoming calls to BREW, 114incoming SMS messages, 115

Terminating dialogs, 93Timers and alarms sample application, 79Tuning speed emulation parameters, 103, 113

UUsage applications, defined, 22, 105

VVirtual code, error when selecting, 144Virtual function table initialization, 122Visual Studio add-ins

Application Wizard, 125automated ARM compiling, 130

WWeb site, BREW, 15

brewsdkuser'sguide

Documents