BREWSDKUser's Guide

QUALCOMM Incorporated
5775 Morehouse Drive

San Diego, CA. 92121-1714
U.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
Contents
Introducing the BREW SDK User’s Guide, 7
BREW documentation, 8
Documentation conventions, 9
Using online manuals, 9
Links, 10
Table of contents and indexes, 10
Printing, 10
Searching for information in BREW documents, 10
Getting additional help for using the Acrobat Reader, 11
BREW acronyms and terms, 11
Requesting new BREW features, 15
For more information, 15
BREW SDK Overview, 16

Installing the BREW SDK, 16
Components of the BREW SDK, 17
How the components interact, 18
BREW SDK directory structure, 20
Device files, 20
Examples directory, 21
Sample applications, 22
The en (system resources) subdirectory, 22
Shared files, 22
Bitmaps directory, 23
Applet directory, 23
MIF directory, 23
Resource directories, 24
About paths and filenames, 25
iii
Contents
BREW Basics, 26
The BREW solution, 26
BREW advantages, 26
The BREW environment, 28
BREW module/interface structure, 30
Using an interface, 30
Becoming an authenticated BREW application developer, 30
BREW Programming Concepts, 32

Overview of applets and modules, 32
About MIFs, 33
BREW ClassIDs, 34
Interface ClassIDs, 34
Applet ClassIDs, 36
Creating instances, 36
Creating applets, 37
Processing applet events, 37
Suspending and resuming an applet, 38
Monitoring incoming SMS messages, 39
Directed SMS messages, 39
How BREW processes incoming SMS messages, 40
Creating new applications, 40
Language-specific system resources, 41
Floating-point operations, 41
Building BREW applications for wireless handsets, 42
ARM Development Suite 1.0.1, 42
ARM Development Suite 1.1, 46
ARM BREW Builder, 47
Comparing ARM BREW Builder and ARM Development Suite 1.1, 47
Accessing shell services, 48
IShell interface, 48
IBase interface, 49
IModule and IApplet interfaces, 49
IModule interfaces, 49
IApplet interface, 50
Events passed to an applet, 50
Tips for event handling, 51
BREW key event dwParam structure, 52
Embedded File System, 53
iv
Contents
BREW Sample Applications, 54

Sample demonstration applications, 55
Sample usage applications, 59
Sample 1: "Hello World", 66
Source code for Sample 1, 67
Sample 2: Using resources, 71
Sample 3: Using timers and alarms, 79
Sample 4: Using files, 83
Sample 5: Using databases, 85
Sample 6: Using sockets, 88
Using Dialogs and Controls, 89

Creating dialogs, 89
Using the Resource Editor to create a dialog, 89
Constructing the dialog manually, 91
Dialog events, 92
Dialog controls, 92
Terminating dialogs, 93
Dialog application example, 93
Using the BREW Emulator, 97

Running the Emulator, 97
Emulator menus and other features, 99
File menu, 100
View menu, 102
Tools menu, 102
Help menu, 104
Backlight toggle, 104
Color support in the Emulator, 104
Running sample applications, 105
Viewing and editing the application source code, 107
Using the Application Manager, 108
Using speed emulation, 112
Configuring devices for speed emulation, 112
Tuning speed emulation parameters and enabling the device, 113
v
Contents
Using TAPI emulation, 114

Handling calls incoming to BREW, 114
Handling incoming SMS messages, 115
Handling calls outgoing from a BREW application, 117
Extending BREW APIs, 119

Declaring the interface, 119
Defining the class, 120
Defining the class functions, 121
Extension Usage, 124
Using Visual Studio Add-Ins, 125

BREW Application Wizard add-in, 125
Automated ARM compiling add-in, 130
Appendix A: SDK Software Backward Compatibility, 133
Appendix B: Event Codes and Key Codes, 135

Event codes, 135
Key codes, 137
Appendix C: Problems and Warning Messages, 139

Emulator problems, 140
Emulator messages, 141
Applet-specific messages, 142
Configurator problems, 143
Configurator messages, 144
MIF Editor messages, 146
Resource Editor messages, 147
Index, 152
vi
Introducing the BREW SDK
User’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 Describes SDK software compatibility issues you may need to be
Backward Compatibility aware of if you have downloaded multiple versions of the SDK
software.
7
Introducing the BREW SDK User’s Guide
Appendix B: Event Codes and Lists event codes and key codes supported by BREW.
Key Codes
Appendix C: Problems and Lists possible problems or messages you may encounter while using
Warning Messages BREW, and provides resolution suggestions.
BREW documentation
This guide is part of an information set that includes the following documents:
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 Image Describes how to use the BREW Compressed Image
Authoring Guide Authoring Tool to create files for displaying and animating
images in your applications.
8
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.
9
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.
10
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
11
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
12
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.
13
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 pertaining to a screen object, such as pixels per row, pixels per
attributes 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.
14
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 brew-request@qualcomm.com. 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.
15
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.
16
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.
17
BREW SDK Overview
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.
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.
18
BREW SDK Overview
fooapp
BREW MIF Editor
Reference:
ClassIDs: Input BREW MIF
Request from Editor Guide
QUALCOMM Supported classes and applets
website Applet titles, icons, thumbnails
Exported classes
Dependancies
Notifications
BREW privileges
Output Preferred Location
fooapp.mif BREW MIF Directory
For example: BREW\Examples\
MIF\Apps\256colors
BREW Resource Editor

Input
Reference:
Strings
BREW Resource
Bitmaps Editor Guide
Dialogs & controls
Output
Application
Developer fooapp.bar, fooapp_res.h
fooapp2.bar, fooapp2_res.h, ...
Location:
BREW \fooapp\
BREW Emulator
Emulates the device in BREW
environment. The developer
fooapp Project in MSVC++IDE can load and test applets and
(fooapp.dsp fooapp.dsw) classes contained in fooapp.
Input
AEEAppGen.c, AEEAppGen.h
AeeModGen.c, AeeModGen.h Reference:
fooapp.c, fooapp.h, fooapp_res.h BREW Sample
Apps Reference:
Output Location BREW SDK
BREW API
fooapp.dll Reference User's Guide
BREW \fooapp\
BREW SDK
User's Guide
BREW Device Configurator
Input
Device bitmap. SampleDevice.bmp
Device objects and attributes:
Keys and key codes
Screen, screen dimensions, pixels
Language and fonts
Device heap size
Model name
Pushed device bitmap
Reference:
Output BREW Device
OEM Configurator Guide
Device res. file: SampleDevice.qsc
Most likely (see Note)
Preferred location:
BREW\Devices
Note: Sample devices are shipped with the
BREW SDK. Usually, OEMs create devices
and Application Developers need not create
them.
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.
19
BREW SDK Overview
BREW SDK directory structure

The root directory of the BREW SDK directory structure is <BREW>. It contains the following
directories:
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.
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.
20
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.
21
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:
Demonstration These applications demonstrate the capabilities of various

applications 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.
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.
22
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.mif
ClockApps.mif
HelloWorld.mif
...
4Grey\
RoadWarrior.mif
ClockApps.mif
HelloWorld.mif
23
BREW SDK Overview
...
256Color\
RoadWarrior.mif
ClockApps.mif
HelloWorld.mif
...
BREW\Examples\MIF\Usage\
Mono\
iimage.mif
idialog.mif
igraphics.mif
...
4Grey\
iimage.mif
idialog.mif
igraphics.mif
...
256Color\
iimage.mif
idialog.mif
igraphics.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.bar
RoadWarrior.bar
...
4Grey\
24
BREW SDK Overview
AEEControls.bar
RoadWarrior.bar
...
256Color\
AEEControls.bar
RoadWarrior.bar
...
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.
25
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.
26
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
27
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.
28
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
Applet Applet Applet Applet Classes
Module Module Module
Applet Applet Applet Applet Classes
OEM MSM (ASIC)

(UI, DRIVERS) Software
29
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.
30
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.
31
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.
32
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.
33
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.dll
sample/foo.mif
sample/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
34
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
35
AEECLSID_WEB Web interface identifier
AEECLSID_WEBUTIL Utilities for web applications
AEECLSID_WINBMP Windows Bitmap Viewer interface identifier
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.
36
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
37
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.
38
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.
39
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.
40
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.
41
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
#-------------------------------------------------------------------
42
SUPPORT_DIR = ..\..\src
SUPPORT_INCDIR = ..\..\inc
SUPPORT_APPIDDIR = ..
TARGET = helloworld # Target name for output files and

object dir
EXETYPE = elf # Target image file format
MODULE = mod # Downloadable module extension
MAKE_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 directory

ARMINC = c:\ads\include # ARM ADS include file directory
ARMLIB = c:\ads\lib # ARM ADS library directory
ARMCC = $(ARMBIN)\armcc # ARM ADS ARM 32-bit inst. set ANSI C

compiler
LD = $(ARMBIN)\armlink # ARM ADS linker
HEXTOOL = $(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 independence

INTERWRK = 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
43
#-------------------------------------------------------------------
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

architecture
ZA = -za1 # LDR may only access 32-bit aligned
addresses
ZAS = -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
44
#-------------------------------------------------------------------
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 specification

OBJ_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 ------------------------------------------------------
45
#===================================================================
# 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.c
AEEAppGen.o : $(SUPPORT_INCDIR)\AEEAppGen.h
AEEModGen.o : $(SUPPORT_DIR)\AEEModGen.c
AEEModGen.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
46
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.
47
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.
48
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.
49
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)
50
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.
51
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.
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.
BREW key event dwParam structure
For the EVT_KEY_PRESS, EVT_KEY_RELEASE, and EVT_KEY events, dwParam contains

OEM-specific values.
52
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.
53
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.
54
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 Interfaces Description and usage Files needed to run

used application on
handset
Address Book IAddrBook A simple address book application. addrbook.mif

IAddrRec This sample application demonstrates: addrbook.mod
IApplet addrbook.sig
• Usage of the IAddrBook and IAddrRec
IDisplay
interfaces in BREW.
IMenuCtl
IModule
IShell
Calender/ IDatabase A simple personal assistant application. calapp.bar

Scheduler IDateCtl This sample application demonstrates: calapp.mif
IDBMgr calapp.mod
• Basic concepts of BREW personal
IDisplay calapp.sig
assistant-like applications.
IMenuCtl
IShell • Usage of Database Manager
ITextCtl (IDBMgr) and Databases
ITimeCtl (IDatabase) interfaces.
• Usage of BREW UI controls: Menu
(IMenuCtl), Text (ITextCtl), Date
(IDateCtl), and Time (ITimeCtl).
Calculator and IDisplay A simple calculator and a handy tip calcapp.bar

Tip Calculator IMenuCtl calculator. calcapp.mif
IModule This sample application demonstrates: calcapp.mod
IShell calcapp.sig
• Basic calculator and computation
functionality in BREW.
• Floating point arithmetic in BREW.
• Use of Soft-Key menu control and
display using BREW fonts.
55

used application on
handset
Clock applications IApplet Various time-related applications. clockapps.bar

• alarm clock IDisplay This sample application demonstrates: clockapps.mif
IMenuCtl clockapps.mod
• countdown • Usage of the ITimeCtl interface to
IModule clockapps.sig
• stopwatch implement various time-related
IShell
functions.
ITimeCtl
Display IDisplay Application that benchmarks display and dispspeedtune.bar

Speed Tune IFileMgr file operations. This application is used for dispeedtune.mif
IGraphics device speed emulation in Emulator. See dispspeedtune.mod
IMenuCtl Configuring devices for speed emulation on dispspeedtune.sig
IShell page 112 for details. testfile.rd
ISound This sample application demonstrates:
IStatic
• 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.
Hello World IApplet A very simple (probably your first) BREW helloworld.mif
IDisplay application that shows Hello World on the helloworld.mod
IModule device screen. helloworld.sig
IShell This sample application demonstrates:
• 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.
56

used application on
handset
Keypad IApplet When a device key is pressed, KeyPad keypad.bar

IDisplay shows the primary key code associated with keypad.mif
IHeap the device key. keypad.mod
IModule This sample application demonstrates: keypad.sig
IShell
• Handling of the EVT_KEY key
event, including processing of
primary key code (contained in
wParam).
Memo IDatabase A basic memo pad application. memoapp.bar

IDBMgr This sample application demonstrates: memoapp.mif
IDBRecord memoapp.mod
• Memo pad implementation using
IDisplay memoapp.sig
ITextCtl for text input and editing.
IMenuCtl
IModule • Persistence of memos using
IShell IDBMgr, IDatabase, and IDBRecord.
ITextCtl • Soft-Key menu control and its
association with ITextCtl.
MIDI IApplet An audio player that plays MIDI, MP3, midiplayer.bar

IDisplay and QCP (PureVoice) formats. midi.mif
IFile This sample application demonstrates: midi.mod
IFileMgr midi.sig
• Player application implementation
IMenuCtl Look for music files
using the ISoundPlayer interface.
IModule under <BREW\
IShell • Controlling playback of an audio file.
examples\midi\
ISoundPlayer • Player UI implementation using Soft-
music>
Key menu control containing images.
• Listing of audio files using IFileMgr
and selection using IFile.
57

used application on
handset
Road Warrior IApplet A TRUE BREW tested application that roadwarrior.mif

IDisplay connects to the California Department Of roadwarrior.mod
IFile Transportation web-server and shows real- roadwarrior.sig
IFileMgr time traffic data for major San Diego
IMenuCtl highways. The web-server URL and
INetMgr highways are configurable.
IWeb
• How to use INetMgr and ISocket
IWebResp
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.
Security IApplet A basic security services application. security.mif

ICipher This sample application demonstrates: security.mod
IDisplay security.sig
• Usage of the IHash, IRSA, and ICipher
IHash
IMenuCtl interfaces.
IModule NOTE: The IHash interface currently
IRSA supports only the MD5 hashing algorithm.
IShell
Socket IApplet A basic net access application. It socket.mif

IDisplay connects to a URL and retrieves data. socket.mod
IModule This sample application demonstrates: socket.sig
INetMgr
• Usage of INetMgr and ISocket.
IShell
Sound IApplet A basic sound services application. sound.mif

IDisplay This sample application demonstrates: sound.mod
IMenuCtl sound.sig
• How to use the BREW ISound
IModule
interface for basic audio services.
IShell
ISound • How to play a predefined BREW tone
and list of tones.
• How to vibrate the device.
• Usage of ISHELL_Beep() with all beep
types.
58

used application on
handset
Webber IApplet An IWeb usage application that accesses a webber.mif

IDateCtl URL and fetches data. webber.mod
IDisplay This sample application demonstrates: webber.sig
IGraphic
• Usage of the BREW IWeb and
IHeap
IWebResp interfaces. The IWeb
IModule
IPeek Interface is the context in which web
transactions are conducted and
IShell
completed. IWeb is the API for dealing
ISource
with BREW's web support. An IWeb
ISourceUtil
interface pointer is designed to be
ITimeCtl
created at application startup,
IWeb
IWebResp 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.
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.
59

used application on
handset
C++ Application IApplet A BREW application written using C++. cppapp.mif

IDisplay This sample application demonstrates: cppapp.mod
IMenuCtl cppapp.sig
• How to take advantage of C++ in
IModule
writing BREW applications.
IShell
IStatic • How to interface with C-based BREW
from a C++ BREW application.
Extension Class IDisplay The BREW Extension Module. The sample extension.mif
Application IModule application uses the Exported Class in the extension.mod
IShell Extension Module. extension.sig
This sample application demonstrates:
• 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 Usage IApplet This applet is used to invoke the Extension extuse.mif
Application IDisplay Class application. extuse.mod
IExtensionCls This sample application demonstrates: extuse.sig
IModule
• Loading a dynamic class module and
IShell
calling functions from it.
60

used application on
handset
I411 Viewer I411 Viewer A viewer application that implements a new b.411
IApplet Viewer interface which overrides the BREW I411Viewer.bar
IAStream IImage interface. I411Viewer.mif
IDisplay This sample application demonstrates: I411Viewer.mod
IImage I411Viewer.sig
• Creation and implementation of the
IMenuCtl
IShell 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.
IDateCtl IApplet Allows the user to create and operate on idatectl.bar

IDateCtl IDateCtl objects that are used to invoke idatectl.mif
IDisplay Calender date related functionality. idatectlusage.mod
IMenuCtl This sample application demonstrates: idatectlusage.sig
IModule
• Usage of the IDateCtl interface.
IShell
IDBUsage IApplet Allows the user to create and operate on idbusage.bar

IDatabase Database objects. idbusage.mif
IDBMgr This sample application demonstrates: idbusage.mod
IDBRecord idbusage.sig
IDisplay • Usage of the IDBMgr, IDatabase, and
IDBRecord interfaces.
IMenuCtl
IModule
IShell
IDialog IApplet Allows the user to create and manage user dialog.bar
IDateCtl interface dialogs. idialog.mif
IDialog This sample application demonstrates: idialogusage.mod
IDisplay idialogusage.sig
• Usage of the IDialog interface.
IMenuCtl
IModule
IShell
61

used application on
handset
IDisplay IApplet Allows the user to create and operate on idisplay.bar

IDisplay IDisplay interface. IDisplay interface offers idisplay.mif
IMenuCtl basic display services. idisplayusage.mod
IModule This sample application demonstrates: idisplayusage.sig
IShell
• Usage of the IDisplay interface.
IFile IApplet IFile interface functions consist of operations ifile.bar

IDisplay performed on files opened by the IFileMgr ifile.mif
IFile interface. ifileusage.mod
IFileMgr This sample application demonstrates: ifileusage.sig
IMenuCtl
• Usage of the IFile and IFileMgr
IModule
interfaces.
IShell
IGraphics IApplet Allows the user to create and operate on igraphics.bar

IDisplay IGraphics objects. IGraphics objects are igraphics.mif
IGraphics used to invoke graphics-related functionality. igraphicsusage.mod
IMenuCtl This sample application demonstrates: igraphicsusage.sig
IModule
• Usage of the IGraphics interface.
IShell
IHeap IApplet Functions allocate and free blocks of iheap.mif

IDisplay memory and return information about the iheapusage.mod
IHeap amount of memory available and in use in iheapusage.sig
IMenuCtl the device.
IModule This sample application demonstrates:
IShell
• Usage of the IHeap interface.
IHTMLViewer IApplet Allows the user to specify a URL and load ihtmlviewer.mif
IDisplay and view an HTML file on the device. ihtmlviewer.mod
IFileMgr This sample application demonstrates: ihtmlviewer.sig
IHtmlViewer
• Usage of the IHtmlViewer interface.
IModule
IShell
62

used application on
handset
IImage IApplet Allows the user to display images. iimage.bar

IDisplay This sample application demonstrates: iimage.mif
IFile iimageusage.mod
• Usage of the IImage interface.
IFileMgr iimageusage.sig
IImage sample.bmp
IMenuCtl
IModule
IShell
ILicense IApplet Allows the user to control application usage. ilicense.mif

IDisplay This sample application demonstrates: ilicense_10days.mif
ILicense ilicense_10min.mif
• Usage of the ILicense interface.
IMenuCtl ilicense_7use.mif
IModule ilicense_dec31.mif
IShell ilicense_expired.mif
ilicense_unlimit.mif
ilicense.mod
ilicense.sig
IMemStream IApplet Allows the user to create and operate on imemstream.bar

IDisplay IMemStream objects. imemstream.mif
IFile This sample application demonstrates: imemstream.mod
IFileMgr imemstream.sig
• Usage of the IMemStream interface.
IMemAStream browsericon.bmp
IMemStream
IModule
IShell
IMenuCtl IApplet Used to create various types of menus from imenuctl.bar

IDisplay which device users can make selections. imenuctl.mif
IMenuCtl This sample application demonstrates: imenuctlusage.mod
IModule imenuctlusage.sig
• Usage of the IMenuCtl interface.
IShell
INetSocket IApplet Allows the user to create and operate on inetsocket.mif

IDisplay INetMgr and ISocket interface objects. inetsocketusage.mod
IModule INetMgr and ISocket objects are used to inetsocketusage.sig
IMenuCtl invoke network connectivity-related
INetMgr functionality.
INetSocket This sample application demonstrates:
IShell
• Usage of the INetSocket interface.
ISocket
63

used application on
handset
INotify IApplet Implements services that allows a user inotify.mif

IDisplay applet to register with the shell to be notified inotifyusage.mod
IMenuCtl when a particular event has occurred inotifyusage.sig
INotify
• Usage of the INotify interface.
IShell
IRinger IApplet Allows the user to create and operate on iringer.bar

IAStream IRingerMgr objects. The IRingerMgr iringer.mif
IDisplay interface offers basic ringer services. iringer.mod
IFile This sample application demonstrates: iringer.sig
IFileMgr AEE_TONE_0.wav
• Usage of the IRinger interface.
IMemAStream AEE_TONE_1.wav
IMemStream
IMenuCtl
IModule
IRinger
IRingerMgr
IShell
IShell IApplet Allows the user to create and operate on the ishellusage.bar
IDisplay IShell object. IShell objects are used to ishell.mif
IMenuCtl invoke system level functionality. ishellusage.mod
IModule This sample application demonstrates: ishellusage.sig
IShell
• Usage of the IShell interface.
ISound IApplet Allows the user to create and operate on the isound.mif
IDisplay ISound object. The ISound interface offers isoundusage.mod
IMenuCtl basic sound services. isoundusage.sig
IShell
• Usage of the ISound interface.
ISound
64

used application on
handset
ISoundPlayer IApplet Allows the user to create and operate on isoundplayer.mif

IDisplay ISoundPlayer objects. ISoundPlayer isoundplayer.mod
IFile interface offers services that play and isoundplayer.sig
IFileMgr operate on MP3 and MIDI sound files. Look for music files
IMenuCtl This sample application demonstrates: under <BREW\
IModule
IShell • Usage of the ISoundPlayer interface. examples\midi\
music>
ISound
ISoundPlayer
IStatic IApplet Allows the user to display static text controls, static.bar
IDisplay consisting of a text message and title. istatic.mif
IImage This sample application demonstrates: istaticusage.mod
IMenuCtl istaticusage.sig
• Usage of the IStatic interface.
IModule
IShell
IStatic
ITAPI IApplet A simple interface to the telephony layer in itapi.mif

IDisplay the device. This function provides the itapiusage.mod
IFile following services: itapiusage.sig
IFileMgr • Retrieving status.
IMenuCtl
• Placing voice calls.
IModule
• Extracting SMS text from SMS
IShell
messages.
ITAPI
• Obtaining caller ID on incoming or in-
progress calls.
• Usage of the ITAPI interface.
ITextCtl IApplet Allows the user to create and operate on itextctl.bar

IDisplay ITextCtl objects. ITextCtl objects are used for itextctl.mif
IMenuCtl basic text entry-related services. itextctlusage.mod
IModule This sample application demonstrates: itextctlusage.sig
IShell
ITextCtl • Usage of the ITextCtl interface.
65

used application on
handset
ITimeCtl IApplet Allows the user to create and operate on itimectl.mif

IDisplay ITimeCtl objects. The time control interface itimectlusage.mod
IMenuCtl has three modes: clock, stop-watch, and itimectlusage.sig
IModule count-down.
ITimeCtl
• Usage of the ITimeCtl interface.
Resource IApplet Usage of BREW string and image resapp.bar

application IDisplay resources. resapp.mif
IImage This sample application demonstrates: resapp.mod
IModule resapp.sig
IShell • 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.
Twin Applet IDisplay Demonstrate the presence of two applets twinapp.mif

IShell within the same module. The module is twinapp.mod
called TwinApp1 and the two applets within twinapp.sig
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.
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.
66
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 definitions
2. #include "AEEAppGen.h" // Applet interface definitions
3. #include "AEEDisp.h" // Display Interface definitions
4. #include "helloworld.bid" // Applet ClassID
5.
6. static boolean HelloWorld_HandleEvent(IApplet * pi, AEEEvent eCode,
7. uint16 wParam, uint32 dwParam);
8.
67
9. // Applet loading function

10. 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 function
28. 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 event
38. IDISPLAY_ClearScreen (pMe->m_pIDisplay); // Erase Screen
39.
40. // Display string on the screen
41. 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
screen
44.
45. return(TRUE);
46. case EVT_APP_STOP:
47. return TRUE;
48. default:
49. break;
50. }
51. return FALSE;
52. }
68
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.
69
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.
70
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.
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
71
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 definitions
2. #include "AEEAppGen.h" // Applet interface definitions
3. #include "AEEShell.h" // Shell interface definitions
4. #include "AEEDisp.h" // Display Interface definitions
5. #include "AEEStdLib.h" // Standard library definitions
6. #include "AEEImage.h" // IImage interface definitions
7. #include "resapp_res.h" // Resource ID definitions
8. #include "resapp.bid" // Applet ClassID
9.
10. #define szResFile "resapp.bar" // Resource file name
11.
12. // Applet specific data structure
13. typedef struct _CResApp
14. {
72
15. AEEApplet a; // Mandatory AEEApplet data member appears first

16. int m_cxWidth; // Stores the device screen width
17. int m_cyHeight; // Stores the device screen height
18. int m_nCursorX; // Stores the cursor bitmap x coordinate
19. int m_nCursorY; // Stores the cursor bitmap y coordinate
20. IImage * m_pIImage; // IImage interface pointer
21. }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 function
30. 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. }
47. }
48.
49. // Applet data initializing function
50. 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 info
59. 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 member
67. if ((pMe->m_pIImage = ISHELL_LoadResImage(pMe->a.m_pIShell,
73
68. szResFile, IDB_CURSOR)) == NULL)

69. {
70. return FALSE;
71. }
72.
73. return TRUE;
74. }
75.
76. // Applet data freeing function
77. static void ResApp_FreeAppData(IApplet* pi)
78. {
80.
81. if (pMe->m_pIImage != NULL)
82. {
83. IIMAGE_Release (pMe->m_pIImage);
84. }
85. }
86.
87. // Event handling function
88. static boolean ResApp_HandleEvent(IApplet * pi, AEEEvent eCode,
uint16
89. wParam, uint32 dwParam)
90. {
91. AEERect rc;
92. AECHAR szBuf[30] = {0};
93.
95.
96. switch (eCode)
97. {
98. case EVT_APP_START: // Applet start event
99. IDISPLAY_ClearScreen (pMe->a.m_pIDisplay); // Erase screen
100. // 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 rectangle
113. 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 screen
117. IIMAGE_Draw (pMe->m_pIImage, pMe->m_nCursorX,
74
118. pMe->m_nCursorY);
119.
120. IDISPLAY_Update(pMe->a.m_pIDisplay);
121. return (TRUE);
122. case EVT_KEY: // process key-down event
123. 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);
138. return TRUE;
139. default:
140. break;
141. }
142.
143. return FALSE;
144. }
145.
146. // Helper function to move bitmap on the screen
147. 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 info
155.
156. // Erase previously displayed bitmap from the screen
157. 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 screen
163. 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
75
172.
173. pMe->m_nCursorX = x; // Store new x coordinates
174. pMe->m_nCursorY = y; // Store new y coordinate
175.
176. IDISPLAY_Update(pMe->a.m_pIDisplay); // Update screen
177. }
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.
76
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.
77
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.
78
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.
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 0x0100FF02
6. #define AEECLSID_ALARMAPP 0x0100FF03
7.
8. static boolean TimerApp_HandleEvent(IApplet * pi, AEEEvent eCode,
10. static boolean AlarmApp_HandleEvent(IApplet * pi, AEEEvent eCode,
79
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. {
24. (IApplet**)ppObj, (AEEHANDLER)TimerApp_HandleEvent,
25. (PFNFREEAPPDATA)TimerApp_FreeAppData) == TRUE)
26. {
28. }
29. }
30. else if(ClsId == AEECLSID_ALARMAPP)
31. {
33. (IApplet**)ppObj, (AEEHANDLER)AlarmApp_HandleEvent,
34. (PFNFREEAPPDATA)TimerApp_FreeAppData) == TRUE)
35. {
37. }
38. }
40. }
41.
42. // Timer Callback Function
43. void TimerCB(void *pv)
44. {
45. AEEApplet * pMe = (AEEApplet *) pv;
46.
47. // Process timer expiration here
48.
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 milliseconds
56. uint16 nCode = 10;
57. uint32 numMinutes = 10; // Alarm activate time: 10 minutes
58.
59. switch (eCode)
60. {
61. // Handle app startup
62. case EVT_APP_START: // Process Start event
63.
64. // Set timer
65. ISHELL_SetTimer (pMe->m_pIShell, timerValue,
80
66. TimerCB, (void *)pMe);

67.
68. // Now set alarm
69. ISHELL_SetAlarm (pMe->m_pIShell, AEECLSID_ALARMAPP, nCode,
70. numMinutes);
71.
72. return (TRUE);
73.
74. case EVT_APP_STOP: // Process Stop event
75.
76. // If timer is still running, cancel it
77. 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 in
82. // 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 event
101.
102. return (TRUE);
103. }
104. return(FALSE);
105. }
81
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.
82
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.
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.
83

1. typedef struct _CFileApp {
2. AEEApplet a; // Mandatory first member of structure
3.
4. // Begin applet-specific data
5. IFileMgr * m_pIFileMgr;
6. IFile * m_pIFile;
7. } CFileApp;
8.
9. ………………………
10.
11. // HandleEvent Function
12. 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 opened
18. byte pBuffer[100]; // Buffer to read data into
19. uint32 dwCount = 100; // Number of bytes to read
20. char szFileName[] = “fileName”; // Name of file to be opened
21.
22. switch (eCode)
23. {
24. // Handle applet startup
25. case EVT_APP_START:
26.
27. // Create an instance of the file manager
28. 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 reading
34. if (pMe->m_pIFile = IFILEMGR_OpenFile(pMe->m_pIFileMgr,
35. szFileName, mode))
36. {
37. // Succeeded in opening file for reading, so now
38. // read first 100 bytes of file into buffer
39. if (IFILE_Read(pMe->m_pIFile, pBuffer, dwCount) == 0)
40. {
41. // Read failed—close the file and exit
42. IFILE_Release(pMe->m_pIFile);
43. return FALSE; // read failed
44. }
45. }
46. // Close the file now that we’ve finished accessing it
47. IFILE_Release(pMe->m_pIFile);
48. }
49. return TRUE;
50.
52. break;
84
53. }
54. return FALSE;
55. }
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.)
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.
85
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, uint16
2. wParam, uint32 dwParam)
3. {
4. const char szDbFileName [] = "dbFileName"; // Database file name
5. AEEDBField dbField[1]; // Database field data instance
6. int nNumFields = 1; // Number of fields in the record
7. const char lastName [] = "Smith"; // Last name of a person
8. 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 manager
20. ISHELL_CreateInstance (pMe->a.m_pIShell, AEECLSID_DBMGR,
21. (void **)pMe->m_pIDBMgr);
22.
23. if (pMe->m_pIDBMgr)
24. {
25. //Open Database
26. if ((pMe->m_pIDatabase = IDBMGR_OpenDatabase (
27. pMe->m_pIDBMgr, szDbFileName, TRUE)))
28. {
29. // Create database record
30. if ((pMe->m_pIDBRecord = IDATABASE_CreateRecord (
31. pMe->m_pIDatabase, dbField, nNumFields)))
32. {
33. return TRUE;
34. }
86
35. }
36. }
37. return FALSE;
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.
87
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.
88
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.
89
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.
90
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.
91
Dialog events
The following three events can be handled by any applet that uses BREW dialogs:
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.
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.
92
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.
93
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.
94
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.
95
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.
96
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.
97
Applets
Select
key
End
key
Clear
key
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.
98
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.
99
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.
100
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.
101
View 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.
Tools menu
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.
102
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.
103
Help menu
About BREW Emulator Opens a window that shows the BREW version and copyright
information.
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:
RGB (0, 0, 0) Black
RGB (0x80, 0x80, 0x80) Dark Grey
RGB (0xc0, 0xc0, 0xc0) Light Grey
RGB (0xff, 0xff, 0xff) White
Color depth of 4:
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
104
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
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:
Demonstration These applications demonstrate the capabilities of various

applications 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.
105
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:
106
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.
107
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.
108
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.
109
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.
110
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.
111
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.
112
• 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.
113
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.
114
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.
115
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.
116
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.
117
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.
118
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)
119
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 structure
DECLARE_VTBL(IExtensionCls)
// Class member variables

uint32 m_nRefs; // References to us
IShell * m_pIShell; // copy of Shell pointer
IDisplay * m_pIDisplay; // Display interface pointer
IModule * m_pIModule; // IModule interface pointer
} ExtensionCls;
120
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.
121
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 object

if(nSize < sizeof(ExtensionCls))
nSize += sizeof(ExtensionCls);
if((pMe = (ExtensionCls *)MALLOC(nSize +
sizeof(VTBL(IExtensionCls)))) == NULL )
return ENOMEMORY;
Virtual Function Table After the memory block for the class and virtual function table is allocated,
Initialization 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 VTBL
modFuncs->AddRef = ExtensionCls_AddRef;
modFuncs->Release= ExtensionCls_Release;
modFuncs->DrawSmiley= ExtensionCls_DrawSmiley;
modFuncs->DrawHello= ExtensionCls_DrawHello;
// initialize the vtable

INIT_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 Member After the virtual function table has been initialized, the next step is to
Initialization initialize each class member, as shown in the following example:
// initialize the data members

pMe->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.
122
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 IDisplay

ISHELL_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 variables
uint32 m_nRefs; // References to us
IShell * m_pIShell; // copy of Shell
pointer
IDisplay * m_pIDisplay; // Display interface
pointer
IModule * 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.
123
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:
Macros
IEXTCLS_AddRef
Applet IEXTCLS_Release
IEXTCLS_DrawSmiley
ExtensionCls_AddRef()
{ IEXTCLS_DrawHello
…
}
IExtensionCls VTBL
{
AddRef
…
}
Release
{ DrawSmiley
…
} DrawHello
{
…
}
124
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.
125
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.
126
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.
127
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.
128
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.
129
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.
130
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:
131
CLEAN
del /f AEEAppGen.o AEEModGen.o helloworld.o
del /f helloworld.elf
del /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.
132
Appendix A: SDK Software
Backward 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 Backward
Release Compatible With Comments
1.1.0.x 1.0.1.x 1) Possible compilation errors can occur for applications

1.0.2.x 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.
133
Appendix A: SDK Software Backward Compatibility
BREW Backward
Release Compatible With Comments
1.0.1.x None None
1.0.0.x None None
134
Appendix B: Event Codes and
Key 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. wParam = 0, dwParam = 0.

Configuration screen shown.
EVT_APP_HIDDEN_ Alternate application start. wParam = 0, dwParam = 0.

CONFIG 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

specific.
EVT_KEY_RELEASE Key release event. wParam = key code (see Key

specific.
135
Appendix B: Event Codes and Key Codes
EVT_KEY_HELD Key held event. The hold time is wParam = key code (see Key
device-specific. Not supported codes table), dwParam = OEM-
in Emulator. specific.
EVT_COMMAND Application custom controls wParam = user command ID,

event. 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 wParam = 0, dwParam =

activated. 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 wParam = DialogID, dwParam =

normally. IDialog *.
EVT_COPYRIGHT_END Dialog event: Copyright dialog wParam = DialogID, dwParam =

ended. IDialog *.
EVT_ALARM Alarm event. wParam = Alarm Code, dwParam

= 0.
EVT_NOTIFY BREW-generated notification or wParam = 0, dwParam =

application-registered AEENotify *.
notification event.
EVT_BUSY Sent to application to determine wParam = 0, dwParam = 0.

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.
136
EVT_FLIP Device-specific event: Sent to wParam = TRUE if open, FALSE if

application when flip-type closed; dwParam = 0.
(clam-shell) device is opened or
closed.
EVT_LOCKED Device-specific event: Sent to wParam = TRUE if locked, FALSE

application when device user otherwise; dwParam = 0.
interface is locked.
EVT_KEYGUARD Device-specific event: Sent to wParam: TRUE if keyguard is on,

application when device keypad FALSE otherwise; dwParam = 0.
is locked.
EVT_USER Start of application/user-defined Private to application.

events.
Key codes
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
137
Key code Value Description
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
138
Appendix C: Problems and
Warning 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
139
Appendix C: Problems and Warning Messages
Emulator problems
The following problems are specific to the Emulator.
Problem Cause Solution
The device image is shown, but The MIF directory is wrong. From Tools > Settings or from
the device screen is blank. File > Change MIF Dir, change
the MIF directory.
The Emulator window is blank Device file is wrong. Possible From Tools > Settings or from
after startup or after changing causes for a wrong device file File > Load Device, change
settings or changing device. include: the device file.
• 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.
While trying to play a MIDI or Possible causes include: First, make sure the file is
MP3 file, the file fails to run. • The file is not present. present and is of MIDI or MP3
format.
• The file is not MIDI or
MP3 format. Next, make sure the operating
• The operating system system is at least Windows NT
version is lower than 4.0-Service Pack 3 or Windows
Windows NT 4.0-Service 2000-Service Pack 2.
Pack 3 or Windows 2000- Finally, make sure the
Service Pack 2. computer has hardware and
• Multimedia capabilities software multimedia
are not present on the capabilities. To verify this,
computer. download and install Windows
• Multimedia software Media Player (version 6.4 and
components are not above for NT, or version 7.0
present in the operating and above for Windows 2000)
system. from the Microsoft web site,
then open and play Sample.mid
and Sample.mp3 under the
<BREW\Bin\DataFiles>
directory.
140
Emulator messages
The following messages are Emulator-specific.
Message Cause Solution
Failed to initialize The heap size specified in the Edit the device file using the
BREW. The heap size ... device file is smaller than what Configurator. Click Details in
(displayed when loading a BREW requires. Attribute View. The Device
device in the Emulator) Attributes dialog box opens.
Increase the heap size, click
OK, save the device, and
reopen in the Emulator.
Failed to initialize Device resource file (.qsc file) is First, make sure the device file
the device either corrupt or contains is in the same directory as the
(displayed when loading a invalid data. device resource file. If it is,
device in the Emulator) 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 The BREW_Emu.dat file may Make sure the BREW_Emu.dat
settings file. be read-only. file is not read-only. The
(displayed in Emulator after BREW_Emu.dat file is under
clicking OK in Settings dialog Brew\Bin directory.
box)
There is no real size Either the screen width or Edit the device file using the
screen info height is 0 (zero). Configurator. Select the screen
(displayed when you choose and update the screen
View > Real Size Screen in the dimension, and then save the
Emulator) device and reopen it in the
Emulator.
Windows has not enough The heap size specified in the Change to another device that
memory... device file is bigger than what has a smaller heap size,
(displayed when loading a Windows can allocate. decrease heap size using the
device in the Emulator) Configurator, or close some
Windows applications.
141
Applet-specific messages
The following messages are BREW applet-specific. These messages are displayed by IShell
on the device screen.
Digital service is The device does not have Ensure that the device is in a
required to use this digital service. digital coverage area.
feature.
Insufficient Memory There was not sufficient On the SDK, increase the
memory to load and execute memory size from the device
the application. configuration file.
On the device, restart the
phone.
Module failed to free The application did not free all Ensure the application does not
all memory. the memory it allocated during have memory leaks. You can
execution. 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 Download the application to the

process failed. This process is device again.
carried out after the application
is downloaded to the device
and before it is executed.
This application has The applet subdirectory or the On the SDK, ensure that the
been unloaded to save applet module (.mod on the applet subdirectory exists and
memory. You must device and .DLL on the SDK) has the same name as the MIF.
download a new version. could not be found. 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.
142
This application has The allowed duration of use for Download the application to the
expired. the application has expired. device again.
Unable to start The application load procedure Debug the application to check
application. failed due to initialization errors. which of the initialization
or This can occur if one or more operations (mainly in
operations failed using the CreateInstance() and handling
Unknown Error
AEEClsCreateInstance() the APP_START event) failed.
function or during APP_START
event processing.
Configurator problems
Problem Cause Solution
When you select an object There are no more free virtual Make sure there are enough
Type of Screen or Key, you codes available. You have virtual codes available for the
are informed that the device created more objects than the created objects. Locate and delete
object cannot be created. total number of free virtual UNDEFINED objects in the
codes available. Created Device Objects list. See
the BREW Device Configurator
Guide for details.
In the device pane, the device The Windows Color Palette or Choose Control Panel > Display
image appears as black and the Number Of Colors field is > Settings. Set the Color Palette
white. set to less than or equal to 256 or Number Of Colors to more than
colors. 256 colors.
The device pane is blank and The main image file is blank, See if the image file is blank.
you cannot proceed further. or you did not specify an Specify the correct image file
image file when creating a when choosing a new file.
new project.
You cannot save the device There is a sharing violation or Check if the device file is used by
(or resource) file. other file permission some other application. Also
problems. check for its file permissions.
While you are creating an The object you are trying to Create objects that are within the
object in the device pane, the create intersects or overlaps device boundary and that are not
rectangle disappears. another object’s boundary intersecting or overlapping with
rectangle. any other objects.
143
Configurator messages
Coordinates out of You entered a value in the In the device pane, select the
device boundary or Coordinates fields and one of object rectangle and use the
intersecting/over- the following problems exists: sizing handles to adjust it. If you
lapping with other need to add a value manually,
• The coordinates of the
objects. . . adjust the Coordinates fields in
object rectangle are
beyond the device the attribute pane.
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.
Error adding primary You tried to assign the primary Always make sure that there
code code for a key object and there are enough virtual codes
are no more free virtual codes available for the created
available. You have created objects. Locate UNDEFINED
more objects than the total objects (use the Created
number of free virtual codes Device Objects list) and delete
available. them. See the BREW Device
Configurator Guide for details.
Error adding virtual You tried to add an overload Do not assign more than five
code code for a key object when overload codes per key object.
there may be too many
overload codes. The
Configurator allows only five
overload codes per key object.
Fatal: Language type You tried to open the Device There is a problem with the
load error Attributes dialog box. binary. Contact BREW
technical support.
144
Pushed Image file not You entered a pushed image Enter the correct image
found, wrong format or file that does not exist, is filename, or leave the field
same as Main Image file corrupted, or is the same as the blank (the pushed image file is
main image file. optional).
NOTE: The Configurator reads
and validates the pushed
image file.
Resource File read You tried to open a .qsc file or Make sure the main image file
error: <cause> load a new image file and one is in the same directory as the
of the following problems resource, and that it is a valid
exists: image.
• Configurator cannot find For all other errors, please
the main image file. contact BREW technical
• Main image file is invalid. support.
• One or more device We recommend that you
objects are out of the modify the device file using the
main image boundary. Configurator, not an editor.
• 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.
The font that you have You selected the system font in Select another font; the system
selected is System the Font dialog box. font does not appear properly in
Font. It does not have the Emulator.
distinct Normal and
Bold characteristics.
Both Normal and Bold
will appear similar. Do
you want to continue
with this font?
145
MIF Editor messages
A required field is You left one or more required Enter a number in the required
empty. Please enter a fields empty. fields.
32-bit hexadecimal
number.
A required field was You left one or more required Enter text in the required fields.
left empty. Please text fields empty.
enter a string.
Are you sure you want to You attempted to use Local Use local ClassIDs for testing
generate a ClassID ClassIDs when submitting an only. Applications submitted
locally? application for BREW using a local ClassID will not
certification. pass BREW certification.
Checking "Show on In the Advanced Applet dialog If you choose Show on Config
Config Menu" and/or box, you selected Show on Menu or Show on Hidden
"Show on Hidden Config Config Menu or Show on Config Menu, specify a Menu
Menu" requires a Menu Hidden Config Menu, without String.
String. specifying a Menu String.
"Menu String" needs to In the Advanced Applet dialog If you enter a menu string, you
be associated with box, you entered a menu string, must choose Show on Config
"Show on Config Menu" but did not choose Show on Menu and/or Show on Hidden
and/or "Show on Hidden Config Menu and/or Show on Config Menu.
Config Menu". Please Hidden Config Menu.
check the applicable.
The file <name> does not The filename you entered Verify that the file exists and
exist. cannot be found. that you spelled the name
correctly.
The MIF file you Version incompatibility. See Appendix A: SDK Software
attempted to open was Backward Compatibility on
produced by an page 133 for a list of backward-
incompatible version of compatible versions and
the MIF Editor and issues.
cannot be opened.
The value cannot be You entered zero in a field that Enter a value, other than 0
zero. Please enter a must be non-zero. (zero).
non-zero 32-bit
hexadecimal number.
146
You must either specify You added a new notification Specify either a custom or
a system class or a without specifying a custom or system class notification when
custom class system class notification. adding a new notification.
notification type.
You must have at least A MIF must contain at least one Specify at least one applet or
one class or applet applet to be saved. class in the MIF and try saving
defined. it again.
Resource Editor messages
An error occurred while This error can occur if the BRI open error:
trying to save the Resource Editor was unable to • If the BRI file is corrupt,
resource file .... open a BRI file, or if the re-create the file.
Resource Editor could not save
• Make sure the file is not
a resource file for one or more
read-only.
of the following reasons:
• Ensure that your PC has
• The file is read-only. sufficient disk space.
• Not enough disk space is • Check the file’s
available to create the permission and sharing
file. settings.
• There is a sharing
Save error:
problem or other file
permission problems. • Make sure the file is in a
• An unknown error format recognized by the
Resource Editor.
occurred.
• Check the file’s
permission and sharing
settings.
For all other errors, please
contact BREW technical
support.
Could not open the "..." The file could not be opened. If the file is read-only, remove
file. Make sure it is that attribute so that it can be
not marked as Read- opened successfully.
Only.
147
No resources to build. There are no resources to To create a valid BAR (output)

The compiled resource compile. file, you must specify at least
file and header files one resource in the resource
will not be created. file.
The control ID in which You are attempting to set initial Make sure that the specified
you wish to set initial focus to a control in a dialog control ID is shown in the
focus is not valid for that does not exist in that Dialog Controls list.
this dialog. Please dialog.
choose a control ID that
exists within this
dialog box.
The control resource ID The ID you specified for the Choose a unique ID. By default
you specified is resource type already exists. the Resource Editor
already used by another automatically generates the ID.
control. Please choose
a unique control
resource ID.
The dialog resource ID The ID you specified for the Choose a unique ID. By default
dialog. Please choose a
unique dialog resource
ID.
The file does not The extension is missing on the Make sure the image file has
contain any extension image file. The image type the correct extension. For
and hence the Image Type cannot be determined, because example, a bitmap file should
(MIME Type) cannot be the image type (MIME type) is have a .bmp extension.
determined. based on the extension.
The image resource ID The ID you specified for the Choose a unique ID. By default
image. Please choose a
unique image resource
ID.
148
The image you have This warning describes the Change the size of the selected
selected is 80 pixels details of the selected image image or select another image
wide, 80 pixels tall, and identifies the dimensions of that is within the size restriction.
and has 8 bits/pixel. a typical image resource.
Typically, image
resources are less than If an image size is larger that
150 pixels wide, 150 the screen size on the phone,
pixels tall, and have 1 the image is clipped.
bit(s)/pixel.
The list item resource The ID you specified for the Choose a unique ID. By default
ID you specified is resource type already exists. the Resource Editor
list item. Please
choose a unique list
item resource ID.
The resource file that BREW version incompatibility. See Appendix A: SDK Software
you are opening is from Backward Compatibility on
a previous version of page 133 for version
the application. The compatibility issues.
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.
The resource name you The ID you specified for the Choose a unique ID. By default
specified is already resource type already exists. the Resource Editor
used by another automatically generates the ID.
resource. Please
choose a unique
resource name.
The string resource ID The ID you specified for the Choose a unique ID. By default
string. Please choose a
unique string resource
ID.
149
The version of the file BREW version incompatibility. See Appendix A: SDK Software
you are opening was Backward Compatibility on
created with a version page 133 for version
of the application that compatibility issues.
is not compatible with
this version. You will
need to obtain an
updated version of this
application in order to
open this file.
You must enter a You have not entered a Enter a valid resource name.
resource name for this resource name for the dialog
dialog. resource.
You must enter a You have not entered a Enter the requested resource
resource name for this resource name for the image name.
image. resource.
resource name for this resource name for the list item name.
list item. resource.
resource name for this resource name for the string name.
string. resource.
You must enter a string You have not entered a string Enter a valid string.
for this resource ID. for this string resource
You must enter an ID for You have not entered an ID Enter a valid ID number.
this dialog resource. number for the dialog resource.
You must enter an ID for You have not entered an ID for Enter the requested ID number.
this image resource. the image resource.
You must enter an ID for You have not entered an ID for Enter the requested ID number.
this string resource. the string resource.
150
You must have at least There are no string resources You must specify at least one
one string resource for in your resource file. string per dialog.
your dialog box(es)
You must specify a You entered an invalid path or Enter a valid path and filename.
path\filename of a filename for the image file.
valid image.
151
Index
A C
Acronyms used in this manual, 11 Case sensitivity of paths on PC and device, 25
Add-ins Changing
Application Wizard, 125 applet directory, 100
automated ARM compiling, 130 application source code, 107
Visual Studio, 125 MIF directory, 101
AEE Class
headers, 33 creating, 36
IBase class, 49 defining, 120
model, 29 methods of defining, 121
API ClassIDs
extensions, 119 applet, 36
interfaces, 30 assigning to applets or classes, 34
Applets interface, 34
changing directory, 100 Cleaning a make file, 131
ClassIDs for, 36 Color support in the BREW Emulator, 104
configuring in the Emulator, 109 Compilation errors, finding and fixing, 132
creating, 37 Controls
directory on SDK, 23 dialog, 92
events passed to, 50 using, 89
overview, 32 Conventions, documentation, 9
processing events for, 37 Creating
resuming, 38 applets, 37
suspending, 38 applications, 40
Application classes, 36
certifying, 30 dialogs, 89, 91
creating new, 40 instances, 36
developing with BREW, 28 make file for application, 131
source code, viewing and editing, 107
Application Manager, configuring applets
with, 108
D
Application Wizard add-in Database management sample application, 85
description of, 125 Defining
files created with, 130 class methods, 121
Authentication, developer, 30 classes, 120
Automated ARM compiling, 130 Device
configuring for speed emulation, 112
directory, 20
B files, 20
Backward compatibility of SDK software, 133 selecting, 100
Bin directory, 20 Device Attributes dialog box, error on
Bitmaps directory, 20 opening, 144
Device Configurator, description of, 17
Device file
cannot save, 143
error on opening, 145
152
Index
Device pane Image file, error when loading, 145

black and white image appears, 143 IModule interface, 49
image is blank, 143 Inc directory, 20
Dialogs Incoming SMS messages, monitoring, 39, 115
application example, 93 Initializing virtual function table, 122
controls, 92 Installing the SDK, 16
creating manually, 91 Instances, creating, 36
creating with Resource Editor, 89 Interfaces
events, 92 ClassIDs, 34
terminating, 93 IApplet, 50
using, 89 IBase, 49
Directed SMS messages, 39 IModule, 49
Directory structure, 20 IShell, 48
DLLs, BREW and OEM, 17 structure, 30
Docs directory, 20 using, 30
Dynamic modules, 49
K
E Key codes, 137
Embedded file system, 53 Key object errors, 144
Emulator Keypress events, 51
changing backlight, 104
color, 104
description of, 17, 97
L
menus, 99 Large font, error when selecting, 145
setting screen size, 102 Links, using, 10
starting, 97
Event
codes, 135
M
handling, 51 Make file
passed to an applet, 50 cleaning, 131
processing, 37 creating for application, 131
Examples directory, 20 Memory allocation, 122
Extending APIs, 119 Menus of BREW Emulator, 99
MIF directory
changing, 101
F description, 23
Features, requesting new, 15 MIF Editor, description of, 17
File management sample application, 83 MIFs, overview, 34
File system, embedded, 53 Module structure, 30
Filenames, entering on PC and device, 25 Monitoring incoming SMS messages, 39, 115
Floating-point operations, 41
Font, error when selecting, 145 N
Normal font, error when selecting, 145
H
Header files, 17
Headers, AEE, 33
O
Hello World sample application, 66 Object technologies, 29
Online manuals, using, 9
Output window, 102
I Overload code, error assigning a code, 144
IApplet interface, 50
IBase interface, 49
153
Index
P System
requirements, 16
Paths, entering on PC and device, 25 resources, language-specific, 41
Primary code, error assigning a code, 144 startup, 33
Printing in online manuals, 10
Processing applet events, 37
Programming concepts, 32 T
Project, creating with Application Wizard, 125 TAPI emulation
Pushed image file, error when loading, 145 calls outgoing from a BREW application, 117
description, 103
R incoming calls to BREW, 114
incoming SMS messages, 115
Readme directory, 20 Terminating dialogs, 93
Requesting new BREW features, 15 Timers and alarms sample application, 79
Resource directory, 24 Tuning speed emulation parameters, 103, 113
Resource Editor, description of, 17
Resuming an applet, 38
U
S Usage applications, defined, 22, 105
Sample application
code for general applications, 54 V
code for incoming SMS messages, 40 Virtual code, error when selecting, 144
Hello World, 66 Virtual function table initialization, 122
resource management, 71 Visual Studio add-ins
running, 105 Application Wizard, 125
shipped with SDK, 22 automated ARM compiling, 130
using databases, 85
using files, 83
using sockets, 88
W
using timers and alarms, 79 Web site, BREW, 15
Screen object
error when creating, 143, 144
rectangle disappears, 143
Screen size, setting in Emulator, 102
Searching within online manuals, 10
Selecting a device, 100
Shared modules, 28
Shell services, 48
SMS messages
directed, 39
monitoring, 39, 115
sample code, 40
Socket sample application, 88
Software, backward compatibility, 133
Sound files, 109
Speed emulation
configuring devices for, 112
enabling, 103
SpeedTune, downloading and running, 112
Src directory, 20
Starting the BREW Emulator, 97
Static modules, 49
Suspending an applet, 38
154

BREWSDKUser's Guide

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

BREWSDKUser's Guide

Transféré par

Droits d'auteur :

Formats disponibles

QUALCOMM Incorporated

5775 Morehouse Drive

Copyright  2001 QUALCOMM Incorporated

BREW SDK User’s Guide

BREW SDK Overview, 16

BREW Programming Concepts, 32

BREW Sample Applications, 54

Using Dialogs and Controls, 89

Using the BREW Emulator, 97

Using TAPI emulation, 114

Extending BREW APIs, 119

Using Visual Studio Add-Ins, 125

Appendix A: SDK Software Backward Compatibility, 133

Appendix B: Event Codes and Key Codes, 135

Appendix C: Problems and Warning Messages, 139

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

Procedures are preceded by a line of blue text

Programming code appears in the manuals like this:

#include "AEEModGen.h" // Module interface definitions

Using online manuals

Table of contents and indexes

Searching for information in BREW documents

To find information in a BREW online manual

The Acrobat Reader opens the manual.

2. Choose Edit > Find.

Getting additional help for using the Acrobat Reader

BREW acronyms and terms

ADS Application Download Server

AEE Application Execution Environment

ANSI American National Standards Institute

APCS ARM Procedure Call Standard

API Application Programming Interface

ARM Advanced RISC Machines

ASCII American Standard Code for Information Interchange

ASIC Application-specific integrated circuit

BDS BREW Distribution System

BREW Binary Runtime Environment for Wireless. BREW is an efficient application

BRI BREW Resource Intermediate. This is the intermediate resource file

CDMA Code Division Multiple Access

CGT BREW Code Generation Tool

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

DLL Dynamic-link library

DTMF Dual Tone Multi-Frequency

EFS Embedded File System

GPS Global Positioning System

GUI Graphical user interface

HTTP Hypertext Transfer Protocol

IDE Integrated Development Environment

ISO International Organization for Standardization

MIDI Musical Instrument Digital Interface

MIME Multipurpose Internet Mail Extensions

MP3 MPEG Audio Layer-3

MSM Mobile Station Modem

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

OEM Original equipment manufacturer

PDA Personal digital assistant

PNG Portable Network Graphics

RAM Random access memory

Resource Editor A tool that generates the resources for applications.

SDI Single document interface

SDK Software development kit

SDT Software development toolkit