Building a Commercial BREW ApplicationPart II Laying the Foundation

The adventurebuilding, testing, and selling a small commercial BREW-based appcontinues. Today we get started by creating our .MIF file, and generating a ClassID for the app.

by Murray Bonner

Sep 17, 2003

Recall that you must use an SDK with a version number that is less than or equal to the version number of the Application Execution Environment (AEE) loaded on the handsets you are targeting. Table 1 lists the handsets we are targeting and their corresponding AEE versions. Note that the size of your target market can be maximized, and TRUE BREW Testing costs can be minimized, by targeting as many phones as possible in a single application submission to National Software Testing Laboratories (NSTL)--because the first 3 submissions are free, after which you are charged $1,000 per submission. In order to target both 1.1 and 2.0 handsets with the same code, we need to use version 1.1 of the BREW SDK for this project. In order for the tools to integrate correctly, please ensure that you have Visual Studio (especially Visual C++) installed before you install the BREW SDK.

Though it's true that we must compile against the version 1.1 header files and libraries, we are not bound to use the other tools included with the 1.1 SDK. In fact, the BREW Emulator included with version 2.x of the SDK provides enhanced heap checking that can make leak-finding a much simpler task. For this reason, I suggest that you first install version 1.1 of the SDK, allowing the installer to set up the various environment variables according to its default behavior. Next, you should install one of the 2.x SDK's in order to obtain the enhanced Emulator.

Getting Started
The BREW Application Wizard provides the easiest way to get a new BREW project under way. After you've installed the SDK, open Visual C++ and select File > New to bring up the new projects dialog, shown in Figure 1. Subsequently, click on "BREW Application Wizard". As shown in Figure 1, I named the project "converter." The project's subdirectory, "\converter," must be placed in the applet directory, which is in this case the default, namely "BREWDirectory\Examples" (i.e. the project's source file will be created in "BREWDirectory\Examples\converter\"). Clicking OK kicks off the BREW Application Wizard.

Figure 2 shows the next step. The checkboxes can be used to specify particular interfaces that you want to use in your project. By placing a checkmark in any of the boxes, you are telling the AppWizard to #include the header file required by that interface. Please select the "File" checkbox and click Next > to move on to Step 2.

In step 2, shown in Figure 3, we are given an opportunity to create a Module Information File, or .mif. As indicated, we could fire up the MIF Editor at this point to create the .mif file needed by the converter application. Just click Finish and move on, for now. We'll create the .mif shortly.

Next, the "New Project Information" dialog pops up (see Figure 4) to summarize the AppWizard's next step. It will generate a source file, converter.c, for our application. We are reminded that the app. needs a .BID (BREW ID) file that must be included in the source file using the preprocessor #include directive. At this point, you need to click the OK button so that the wizard can go ahead and create converter.c.

Next time, we'll discuss the code the AppWizard generated. At this point, creating the .BID file and the .mif makes sense, as the application will not run without them.

For a commercial application, you need to visit the BREW extranet website (see Figure 5) since it is the only source for ID's that are guaranteed unique. The AEE uses this ID to distinguish between different applications on a device, and in the BREW Emulator.

Problem: You can only access this site if you have been Authenticated as a BREW Developer.

Solution: If you are not yet ready to spend $400 on a VeriSign Class 3 Certificate, you can create a .bid locally, using the MIF Editor. I'll show you how to do this.

To illustrate an important concept, let's use the MIF Editor that came with version 2.x of the SDK to create converter's .mif file. Note that version 2.x .mif's include certain features that their version 1.0 kindred do not. Since we want the .mif to work on both 1.1 and 2.x devices, it is important that we use the lowest common denominator and save the .mif as version 1.0 (see Figure 12).

Figure 6 shows the MIF Editor as it appears upon startup. Note that, since I am an authenticated developer and the point of this exercise is to commercialize the application, I created a .bid file using the web-based generator shown in Figure 5. Thus, when I created my .mif, I selected the "Browse for BID File..." button and selected the file I downloaded from the extranet. If you are following along and wish to create a .bid file locally, you can simply click the "New Applet..." button to bring up the dialog presented in Figure 7.

You are given a choice between creating a ClassID (that is, a .bid file) using the Web-based generator or locally. Note that every commercial application must have a unique ClassID. Since you are merely following along for the sake of learning, a locally generated ClassID will suffice.

Please select "Locally," in spite of the warning, and type in an 8-digit hex value. To avoid conflicting with the sample applications included with the SDK, stay away from values between 0x01000000 and 0x02000000, or just set up your own MIF directory and ensure the Emulator points to it (please see the BREW SDK User's Guide that came with your SDK for instructions relating to Emulator use). On an actual device, you should ensure that a locally generated ClassID does not conflict with any commercial BREW application. If two .mif's contain the same ClassID, one of the applets (the last one encountered as the AEE scans for applications) will fail to display.

When you click "Generate", the cautionary message shown in Figure 8 will display. Just click "Yes" and a .bid file will be generated, based on the ClassID you supplied.

Next, you will be prompted to save the .bid file. It should be saved in "BREWDirectory\Examples\converter\". We'll #include it in the converter.c source file in the next installment.

Now that we have a .bid file, we are automatically returned to the MIF Editor's "Applets" tab, where the ClassID is displayed in the drop-down list box. We can now fill in the remaining information, as shown in Figure 9. The "Name:" box holds the name that the Emulator's application manager will display when the converter is selected. Unimaginatively, I filled it in with "Converter". I then specified "Tools" as the "Applet Type" and provided the path to the application's 26 x 26 pixel icon. This icon will be used to launch the application, from the Application Manager screen, on most devices.

You can use the image editor provided with Visual Studio, MS Paint, Paintshop Pro, or whatever tool you prefer, to create the bitmaps that need to be included in the .mif. Note that the background for each of the images included in the .mif must be set to the transparent color, magenta (RGB 255, 0, 255), or the application will fail test case 3.9.5 during True BREW Testing. (See the document "Application Developer's TRUE BREW Test Guide: Requirements and Test Cases.")

Figure 10 shows the MIF Editor's "Advanced Applet Information" dialog. For this application, we only need to provide paths to the two remaining images that need to be included in the .mif. As you might have guessed from the file name, the large image is 65 x 42 pixels. As shown in Table 2, this corresponds with the lowest common denominator for all the handsets we're targeting with this application (specifications for each handset are available in device data sheets, accessible to authenticated developers on the BREW Developer Extranet). By using the same image for all handsets, we'll keep the resource file small, thereby minimizing the download time for the converter applet. (More on the resource file in a later article.)

Don't spend much time creating the large image, as the only place it is used is on the BREW Emulator. None of the devices we are targeting use this image for any purpose. In order to pass TRUE BREW TESTING, however, the image needs to be included in the .mif file. Go figure!

The last required image is a 16 x 16 pixel thumbnail that will be used to identify the application on some handsets. This image must also be created as a bitmap.

Lastly, Figure 11 shows important information that must be entered on the "General" tab of the BREW MIF Editor. You should enter, at minimum, an author name and a copyright string. Note that you can only enter a maximum of 23 characters in each of these two fields. Notice that the "File" checkbox is selected in the "Privilege Level" group. This must be checked since the converter application will use a local file to read and write currency exchange rates. If this option is not selected, and the application attempts to create or access a file on the device or emulator, an error message will inform you that a privilege violation has occurred and the application will not run.

Note that you must provide a module version number for your application (a module). Recall, however, that we are using version 2.0 of the MIF Editor to create a .mif that must be compatible with version 1.1 of the AEE. A version 1.0 .mif cannot include a version number, so I've left that field blank. We'll still need to provide a version number somewhere in the converter application. For more detailed information about using the MIF Editor, please see the MIF Editor Guide that is included with the free SDK.

Now that we've completed a rudimentary .mif for our application, we need to save it. When you save the file, please ensure that "BREW Module Information Files v 1.00..." is selected in the "Save as type" drop-down list box. If you don't do this, the application will fail to display on 1.1 devices because the AEE won't be able to recognize the .mif. If you use version 1.x of the MIF Editor to create the .mif, you don't need to worry about selecting a file format, since 1.00 is the only one available.

Next Time
I had hoped to cover the skeleton source produced by the AppWizard, the BREW Resource Editor, and the final steps required to finish setting up the development environment. In the next installment, we'll see how far we can get without letting any individual tutorial go beyond "bite size".

Originally published in the BREW Wireless Resource Center

Murray Bonner is President of Golden Creek Software Inc., a BREW software developer and a provider of custom training and software development services. Murray has been working with the BREW SDK for nearly 2 years and writes to share his BREW development experience, gained mostly at the expense of his hairline.
.