ContentApplication Data......................................................................................3

Address Book............................................................................................................................3Database & Files.......................................................................................................................3Sharing Data, App Preferences.................................................................................................4

Controls.....................................................................................................7Date and Time Controls............................................................................................................7Dialogs......................................................................................................................................8Menu Control..........................................................................................................................11Text and Static Controls..........................................................................................................13

Creating BREW™ Applications...........................................................16Compiling BREW Applications..............................................................................................16Debugging BREW Applications.............................................................................................19Localizing BREW Applications..............................................................................................24Operating Systems and Processors.........................................................................................27Portability...............................................................................................................................28Uploading BREW Applications to Handsets..........................................................................29Writing BREW Code..............................................................................................................29

Event Handling.......................................................................................33Media.......................................................................................................37

Display and Images.................................................................................................................37Sound......................................................................................................................................44

Memory Management............................................................................47MIF Settings............................................................................................49

Extensions...............................................................................................................................49License....................................................................................................................................53MIF Images.............................................................................................................................56Privileges................................................................................................................................57Screensaver.............................................................................................................................58Other.......................................................................................................................................60

Miscellaneous..........................................................................................61Networking and TAPI............................................................................64

Network Programming............................................................................................................64Telephone API and SMS.........................................................................................................75

Position Location....................................................................................79TRUE BREW® Testing.........................................................................79Known Issues - BREW SDK™, Tools, BDS Known Issues................84

1

Application Data

Address Booka. Why have some OEMs published their own AddrBook.h file?

Applicable Releases: 1.1, 2.0 Some OEMs add to the and address book fields that are provided by BREW (BREW provided categories and address book fields are contained in AEEAddrbook.h). These fields are defined in an OEM-supplied AddrBook.h file that is posted on the Phone Details section of the Developer Extranet.

b. Do I have to call IADDRBOOK_Release to release the record after I remove the record using IADDRBOOK_Remove? Applicable Releases: 1.1, 2.0 A call to IADDRBOOK_Remove automatically makes a call to IADDRBOOK_Release. You do not need to "release" the address book object after you "remove" it.

c. Does my application have to validate the lengths of the fields used to create a record? Applicable Releases: 1.1, 2.0 Each OEM specifies a maximum allowable value for each field of an addressbook record. OEMS may or may not validate the length or values of the fields that your application passes to it by calling IADDRBOOK_CreateRecord. It is advisable for any app that creates addressbook records to validate the length and value of the fields against the maximum allowable length.

d. What is the behavior of IADDRBOOK_CreateRec() when AEEAddrCat is set to a value that is not supported on the handset? Applicable Releases: 1.0, 1.1, 2.0 The behavior of IADDRBOOK_CreateRec() is OEM dependent. OEMs may choose to create the record by mapping to the default category or they might choose not to create the record at all (return NULL).

Database & Filesa. How do I sort database records?

Applicable Releases: 1.0, 1.1, 2.0 There is currently no API available for sorting database records.

b. How do I connect to an external database? Applicable Releases: 1.0, 1.1, 2.0 BREW does not provide a client-side module to connect to an external database such as Oracle, MS Sequel, etc. You can write your own client side module to connect to the external database using the standard socket mechanism provided by BREW.

2

c. How many bytes can be stored in the database? Applicable Releases: 1.0, 1.1, 2.0 This is device dependent. Database files are stored on the device file system, and so depends on the amount of file system space on the device.

d. How does IDBRECORD_Update() work? Applicable Releases: 1.0, 1.1, 2.0 If the size of a database record's old content is the same as the size of its new content, then the record is updated with the new content. If the size of the new content is not the same as that of the old content, a new record is added to the database and the old record is marked for deletion. When the number of records marked for deletion reaches a pre-defined OEM limit (limit is 5 on Kyocera 3035), the records will be physically deleted. Additionally, when a database that has records marked for deletion is closed and subsequently reopened, the records marked for deletion are physically removed during the database open.

e. Please explain the database indexing scheme used in BREW. In BREW SDK™ Version 1.1 onwards, a database record maintains the same index (Record ID) throughout the life of the database, unless deleted. In BREW SDK Version 1.0.1, however, this is not the case.

When a database record is deleted, it is marked for deletion. When the number of records marked for deletion reaches a pre-defined OEM limit (5 on Kyocera 3035), the records will be physically deleted. The records are also physically deleted when the database is closed and reopened (the records are deleted during the open). In BREW SDK Version 1.0.1, when the record(s) are physically deleted, the indices of all database records after the deleted record will change. Therefore, in version 1.0.1, the database record index is not unique. This has been fixed in version 1.1.

f. What is the maximum length (number of characters) allowed for a file name? Applicable Releases: 1.0, 1.1, 2.0 This limit is set by the OEM, and not by BREW. Please refer to the Device Data Sheet (available on the Developer Extranet) for information on maximum file path length. This limit is on the full file path, i.e. the length of the file name with its directory structure.

Sharing Data, App Preferencesa. How can I share resources between multiple modules?

Applicable Releases: 1.0, 1.1, 2.0 By default, file access privileges for dynamically loaded BREW™ modules are restricted to the application directory and its subdirectories. The need may arise, however, for modules to share resources or other types of files; for these situations BREW provides a shared directory, AEE_SHARED_DIR. The actual shared directory path may differ from one device to another. When running on the BREW Emulator the shared directory can be

3

found in the examples directory, with the name "Shared."

Any module may read files from the shared directory. However, to create or write to files in the shared directory the application's privilege level must be modified, using the MIF Editor, to allow "write" access to the shared directory (see the BREW MIF Editor Guide).

A fully qualified path to the directory may be constructed as follows:

char sharedBarFile[20];SPRINTF(sharedBarFile, "%s/%s", AEE_SHARED_DIR, "shared.bar");

On a Kyocera 3035 phone, for example, the preceding code will fill "sharedBarFile" with "/brew/shared/shared.bar", which can then be used to load resources from a shared .bar file. This technique is applicable to any type of file that needs to be shared between applications.

b. How can I pass data from one application to another? Applicable Releases: 1.0, 1.1, 2.0 You can share data between applications by creating a file/database in the shared data location. Please refer to How can I share resources between multiple modules?

Another way to pass data from one application to another is through the ISHELL_SendEvent() or ISHELL_PostEvent functions, although this is not the recommended method. The event-specific 32-bit value (dwParam) parameter in these two functions can be made to point to a data structure in App A. When App B receives the event, it should immediately make a copy of the data. This is important, because if App B decides to start itself up in response to the event, App A may be stopped and unloaded if there isn't sufficient RAM to start App B, thus invalidating the pointer App A supplied to App B in dwParam.

For example: // App A// Data to be passed to App B is a wide string: pMe->myStringISHELL_SendEvent(pMe->a.m_pIShell, AEECLSID_APP_B, EVT_USER, MY_USR_EVT, (uint32) pMe->myString);

//App Bcase EVT_USER:if(wParam == MY_USR_EVT) {AECHAR* data = WSTRDUP((AECHAR*)dwParam);

// Can start app B by calling ISHELL_StartApplet???br> ???br> FREE(data);return TRUE;}

4

Please note that an application is not guaranteed to receive all events sent/posted to it. For example, consider a device whose available heap is 60K. Say the size of App A is 45K, and that of App B is also 45K. If App A tries to send/post an event to App B, App B will not be loaded due to RAM limitations and the event will be dropped.

c. When an application is deleted, are all its files in the shared directory also deleted? Applicable Releases: 1.0, 1.1, 2.0 In BREW 2.0 onwards, files created by the application in the shared directory will be removed when the application is removed.

In BREW 1.0 and 1.1, files created by the application in the shared directory will not be removed when the application is removed.

d. What effect does removing/ disabling/ renewing an application have on application preferences? Applicable Releases: 1.0, 1.1, 2.0 Application removed/disabled using Mobile Shop:If an application is removed, the application's data and preferences are also deleted.

There is a bug in version 1.x, wherein the preferences are not removed when an application is removed. Please refer to Preferences not removed when application is removed for more information. This has been fixed in BREW Version 2.0.

If an application is disabled, the application's data and preferences are not deleted.

If an application has expired, purchasing new uses will not affect the application preferences.

Application removed using BREW App Loader:If an application is removed using BREW App Loader, the application's preferences will linger.

e. Where are preferences set using ISHELL_SetPrefs stored? ISHELL_SetPrefs() stores preference information in a BREW database that is external to your application: appprefs.idx and appprefs.dat. The preferences are stored in appprefs.dat. Appprefs.idx provides the index to the preference data contained in appprefs.dat. The index is based on the Class ID and Preference Version Num specified in ISHELL_SetPrefs().

These files are managed by BREW. If the appprefs.* files do not exist on the handset, then they are created the first time that ISHELL_SetPrefs() is called. To see what effect removing/disabling a BREW application has on its preferences, please refer to What

5

effect does removing/ disabling an application have on application data and preferences.

f. How do I save state across multiple applet reinstalls? Applicable Releases: 1.0, 1.1, 2.0 You can store a structure containing the applet's state in the applet's Preference Database using ISHELL_SetPrefs() and ISHELL_GetPrefs(). Please refer to ishellusage example for information on how to use ISHELL_SetPrefs() and ISHELL_GetPrefs().

Controls

Date and Time Controlsa. How do I get the time in seconds since Jan 6, 1980 (device reference time)?

Applicable Releases: 1.0, 1.1, 2.0 Use GETSECONDS() as shown below:uint32 timeInSeconds = GETSECONDS();

This returns the number of seconds (adjusted for local time) elapsed since Jan 6, 1980 00:00:00 GMT.

The above also applies for GET_SECONDS(), which has been deprecated in BREW™ 2.0.

b. How do I get the current date? Applicable Releases: 1.0, 1.1, 2.0 To get current date, call GETJULIANDATE() and extract information from the filled JulianType structure.

For example:JulianType julianDate;uint32 timeInSeconds;uint16 year, month, day;

GETJULIANDATE(0, &julianDate);

year = julianDate.wYear;month = julianDate.wMonth;day = julianDate.wDay;

To initialize an IDateCtl with system time, use the extracted information from JulianType to call IDATECTL_SetDate().

For example:

IDATECTL_SetDate(pMe->p_date, julianDate.wYear, julianDate.wMonth,

6

julianDate.wDay);

The above also applies for GET_JULIANDATE(), which has been deprecated in BREW 2.0.

c. GETTIMEMS() works on the emulator, but not on the phone. Why? Applicable Releases: 1.0, 1.1, 2.0 There is a bug in GETTIMEMS() and ISHELL_GetTimeMS() in BREW versions 1.x and 2.0. Please refer to GETTIME_MS() works on the emulator, but not on the phone.

The above also applies for GETTIME_MS (), which has been deprecated in BREW 2.0.

d. GET_JULIANDATE() works on the emulator but not on the phone. Why? Applicable Releases: 1.0 This is a bug in SDK version 1.0. Please refer to GET_JULIANDATE() works on the emulator, but not on the phone. This has been fixed in BREW 1.1 - in BREW 1.1, both the emulator and the handset return JulianDate.wWeekDay with the values 0..6, where 0 = Monday and 6 = Sunday.

Please note that GET_JULIANDATE() has been deprecated in BREW 2.0. GETJULIANDATE() should be used instead.

Dialogsa. How do I create a dialog?

Applicable Releases: 1.0, 1.1, 2.0 Use the BREW™ Resource Editor to create a dialog. You can also construct the dialog manually by creating data structures in your application to define the contents of the dialog. Please refer to the "Using Dialogs and Controls" section of the BREW SDK™ User's Guide and the BREW Resource Editor Guidelines document for more details).

Once the dialog has been created, it will have a resource ID and a resource file (.bar file). Use ISHELL_CreateDialog() to create the dialog:

ISHELL_CreateDialog(pMe->a.pIShell, SAMPLEAPP_RES_FILE, RESOURCE_ID, NULL);// SAMPLEAPP_RES_FILE is the resource file (.bar file) and // RESOURCE_ID is the resource ID specified in the resource editorProcess the following events (return TRUE at the very least) in the app handler function:case EVT_DIALOG_START:return TRUE;case EVT_DIALOG_INIT:return TRUE;case EVT_DIALOG_END:return TRUE;

7

Call ISHELL_EndDialog when the dialog object is no longer needed.ISHELL_EndDialog(pMe->a.pIShell);

For more information, please refer to the "Using Dialogs and Controls" section of the BREW SDK User's Guide.

b. How do I create a Dialog Control having other controls programmatically (not using the resource editor)? Applicable Releases: 1.0, 1.1, 2.0 We recommend using the Resource Editor to create dialog controls, unless absolutely required to create them programmatically. To create a dialog control programmatically, follow the steps outlines below:

1. You should know before hand as to how many controls you would like to create (to prevent possible heap corruption).

2. You will have to allocate "contiguous memory" in the heap for your dialog controls as shown below.

di = (DialogInfo *) MALLOC (sizeof(DialogInfo) + (2 * sizeof(DialogItem)));

The above memory allocation is for a dialog owning 3 controls. DialogInfo has 1 DialogItem in its structure. So we allocate memory for just 2 more DialogItem. So for example if you want to create a Dialog with 5 controls, you should use: MALLOC (sizeof(DialogInfo) + (4 * sizeof(DialogItem)).

3. Above memory allocation assumes that you have just 1 DListItem for each control. For Text Control, there are no DListItem, while for a control like Menu Control, it will have as many DListItems as the number of Menu Items.

In cases where you would require more than 1 (more than 1 because, DialogItem struct already has 1 DListItem), you would need to allocate memory as follows.

di = (DialogInfo*) MALLOC(sizeof(DialogInfo) + 2*sizeof(DialogItem) + 6*sizeof(DListItem));

The above memory allocation is for a dialog owning 3 controls and each of the control owns 3 DListItems.

4. After you have allocated proper amount of memory, you fill in the DialogInfo and DialogItem structures as follows

di->controls[0].h.cls = AEECLSID_MENUCTL;

8

di->controls[0].h.wID = IDMNU;...

And then, after you are done creating di->controls[0], append the next control to it as shown below ..

// Create control 1Control1.h.cls = AEECLSID_TEXTCTL;Control1.h.wID = IDTXT;......

MEMCPY((void *) ((long)&di->controls[0] + sizeof(DialogItem)), &Control1, sizeof(DialogItem));

// Create control 2 // Ideally you would use the same control variable to limit stack allocationsControl2.h.cls = ...;......MEMCPY((void *) ((long)&di->controls[0] + 2 * sizeof(DialogItem)), &Control2, sizeof(DialogItem));

5. Now, for example if your Menu Control (control 2 above) owned 3 DListItems, you will have to MEMCPY the DListItem as follows

MEMCPY((void *) ((long)&di->controls[0] + 2 * sizeof(DialogItem) + sizeof(DListItem)), &DListItem1, sizeof(DListItem1));MEMCPY((void *) ((long)&di->controls[0] + 2 * sizeof(DialogItem) + 2 *sizeof(DListItem)), &DListItem2, sizeof(DListItem1));

Above, you will notice that you do not have to MEMCPY the DListItem0, since it is already a part of the DialogItem for the Menu Control.

6. If your control does not have any DListItem (i.e nItems = 0), you will have to make changes in your MEMCPY calculation for the subsequent control that will be added as follows:

MEMCPY((void *) ((long)&di->controls[0] - sizeof(DialogItem)), &Control2, sizeof(DialogItem));

Above would be the case when Control1 had 0 nItems.

7. Now you can use ISHELL_CreateDialog() function with the created DialogInfo as the

9

parameter to create your Dialog Control.

Menu Controla. My menu is larger than the screen size. How do I create a scroll bar?

Applicable Releases: 1.0, 1.1, 2.0 If menu control contains more items than what can be displayed inside the menu control rectangle (specified by IMENUCTL_SetRect), the scroll bar is created. If the menu control rectangle exceeds the screen size, then the menu control rectangle must exceed the screen height by at least the height of a single menu item. Otherwise the menu item will be clipped and no scroll bar will appear.

b. How can I add images to the items in an IMENUCTL? Applicable Releases: 1.0, 1.1, 2.0 You can use the IMENUCTL_AddItemEx method with CtlAddItem structure. Please see the IMENUCTL example in your Examples directory.

c. Can I remove the multitap item from the softkey menu associated with my text control? Applicable Releases: 1.0, 1.1, 2.0 Yes. You can remove it by following the steps outlined below:1. Associate the soft key menu with your text control using ITEXTCTL_SetSoftKey()2. Call IMENUCTL_DeleteAll() to delete the Multitap item3. Add items using IMENUCTL_AddItem()

d. Can I specify a different color of each of my menu items? Applicable Releases: 1.0, 1.1, 2.0 It is only possible to distinguish the appearance of the selected items from the remaining unselected items. This can be done using IMENUCTL_SetColors() and IMENUCTL_SetStyle(). It is not possible to color individual menu items.

e. I am unable to set the colors of selected/ unselected Menu Items using IMENUCTL_SetColors(). Why? When setting the menu color, it is imperative to correctly set AEEMenuColors.wMask.

For example:AEEMenuColors menu_colors;

// Unselected menu item backgroundmenu_colors.wMask = MC_BACK;menu_colors->cBack = MAKE_RGB(0,0,0);menu_colors->cText = MAKE_RGB(0,0,102);IMENUCTL_SetColors(pMe->m_pISKMenu,&menu_colors);

// Selected menu item background

10

menu_colors.wMask = MC_SEL_BACK;menu_colors->cSelBack = MAKE_RGB(64,64,128);menu_colors->cSelText = MAKE_RGB(255,255,255);IMENUCTL_SetColors(pMe->m_pISKMenu,&menu_colors);

IMENUCTL_Redraw(pMe->m_pISKMenu);

The various values for AEEMenuColors.wMask are: MC_BACK Unselected item backgroundMC_TEXT Unselected item textMC_SEL_BACK Selected item backgroundMC_SEL_TEXT Selected item textMC_FRAME Simple frame colorMC_SCROLLBAR Scrollbar frame colorMC_SCROLLBAR_FILL Scrollbar fill color

These two mask is supported only for list controls. MC_TITLE Title background color.MC_TITLE_TEXT Title text color.

f. Is it possible to turn off the scroll bars on an IMenuCtl that exceeds the Screen size? Applicable Releases: 1.0, 1.1, 2.0 No, it is not possible to suppress the MenuCtl's scroll bar if the menu control's size is larger that that of the screen.

g. How do I remove the text associated with an Icon View Menu item? Applicable Releases: 1.0, 1.1, 2.0 It is not currently possible to remove the text of an Icon View Menu item.

h. How do I change the font size of a Menu Item? Applicable Releases: 1.0, 1.1, 2.0 You can change the menu item font using the IMENUCTL_AddItemEx()

For example:CtlAddItem pai;

pai.wText = IDS_ITEM1_TEXT;pai.wImage = IDB_ITEM1_BMP;pai.wItemID = IDS_ITEM1_ID;pai.wFont = AEE_FONT_LARGE;

IMENUCTL_AddItemEx(pMe->m_pStdMenu, &pai);

11

i. How do I recalculate the maximum height of the menu control's items after a menu item has been changed? Applicable Releases: 1.0, 1.1, 2.0 In BREW SDK versions 1.0, 1,1 and 2.0, invoking IMENUCTL_SetStyle() will NULL style parameters after you have called IMENUCTL_SetItem() will recalculate the new maximum height of the menu control items.

In a future BREW SDK release, IMENUCTL_SetItem() will recalculate the new maximum height thus eliminating the step above.

Text and Static Controlsa. How do I move the cursor to the end of the text input? Applicable Releases: 1.0, 1.1, 2.0 In SDK 2.0 onwards, you can move the cursor position using ITEXTCTL_SetCursorPos().

Prior to 2.0, the following code can be used to move the cursor position to the end of the line:

The cursor can be moved to the end of the string by continuously invoking ITEXTCTL_HandleEvent() method n times on the string, where n is the length of the string.

For example:

while(len) {

ITEXTCTL_HandleEvent(pMe->m_pIText, EVT_KEY, AVK_RIGHT, dwParam);

len--;

}

Please note that this does not currently work on the Kyocera 3035, unless dwParam is set to 10 (corresponds to AVK_RIGHT). Setting dwParam = 10 will not have any adverse affect on other handsets.

b. How can I find out the cursor position in a Text Control? Applicable Releases: 1.0, 1.1, 2.0 In BREW™ 2.0 onwards, you can get the cursor position of an ITextCtl using ITEXTCTL_GetCursorPos(). In BREW 1.x, you can monitor the AVK_LEFT and AVK_RIGHT events to determine the position of the cursor.

c. How do I create a text control with horizontal and vertical scrollbars? Applicable Releases: 1.0, 1.1, 2.0 If the text is larger than the Text Control size, then a vertical or horizontal scrollbar will appear and you can navigate through the text using the directional keys.

d. What is the difference between Multi-tap and T9 text entry modes for text input? Applicable Releases: 1.0, 1.1, 2.0 In Multi-tap mode, a key must be tapped several times in order to specify a letter. For

12

example, to specify the letter 'r', tap the number '7' three times. In T9 mode, a key is tapped only once per letter. T9 Text Input determines the most commonly used word matching the input numeric sequence. If more than once word matches the sequence, the most common word is selected, with the ability to scroll to the next most commonly used word.

The default text entry mode is Multi-tap. T9 text entry mode is not currently supported on the emulator.

e. How do I allow the input of symbols in my text control? Certain limited symbol entry is available by pressing a certain key (usually 1) multiple times. This set of symbols is OEM dependent. For example, on the Kyocera 3035, the following symbols are available by pressing the '1' key multiple times: .&@,-':;?/"(). On the Sharp Z-800, the following symbols are available by pressing the 1 key multiple times: .,@:!?/.

To allow a greater breadth of symbol entry in your text control, you must associate your text control to a soft key menu using ITEXTCTL_SetSoftKeyMenu(). The set of symbols

commonly available using this method are: -.&'()_!?*#%":+<>=俊 ""/\@,~{}$[]^;. This is also OEM dependant, some platforms may have different Symbols available, please see the device data sheet.

ITEXTCTL_SetSoftKeyMenu() adds an item to the Soft Key menu that allows the user to change the text entry mode (the text string for this item is the currently selected mode - for example, MultiTap). When it receives this command, the text control displays a menu allowing the user to select the new text entry mode. After the user selects the new mode, the text control is reactivated and the user may continue to enter text. When entering text, the user may press the Select Key to leave text-edit mode and activate the SoftKey Menu. While the Soft Key menu is active, the user may press the UP key to return to edit mode without making a menu selection.

The following is an example of how to allow multiple input modes in your text control:

// Create text controlISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_TEXTCTL, (void **)&pMe->m_pIText);

if (pMe->m_pIText) {// Create soft key menuISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_SOFTKEYCTL, (void **)&pMe->m_pISoftKey);if (!pMe->m_pISoftKey) {ITEXTCTL_Release (pMe->m_pIText);pMe->m_pIText = NULL;return FALSE;}

13

}else {return FALSE;}// Set the soft key menu rectangleIMENUCTL_SetRect(pMe->m_pISoftKey, &softKeyRect);

// Set text control title, size, properties, rectangleITEXTCTL_SetTitle(pMe->m_pIText, NULL, NULL, titleString);ITEXTCTL_SetMaxSize(pMe->m_pIText, 100);ITEXTCTL_SetProperties(pMe->m_pIText, TP_FRAME | TP_MULTILINE );ITEXTCTL_SetRect(pMe->m_pIText, &rect);

// Initialize the softkey menu of the text control.ITEXTCTL_SetSoftKeyMenu (pMe->m_pIText, pMe->m_pISoftKey);

// Set both the soft key and text control active.IMENUCTL_SetActive(pMe->m_pISoftKey,TRUE);ITEXTCTL_SetActive (pMe->m_pIText, TRUE);

In the app's HandleEvent function, you must handle the EVT_KEY and EVT_COMMAND events as follows:

case EVT_COMMAND: // Process EVT_COMMAND event - change of input modeif((pMe->m_pIText != NULL) && ITEXTCTL_HandleEvent(pMe->m_pIText, eCode, wParam, dwParam)) {return TRUE;}return FALSE;

case EVT_KEY: if ((pMe->m_pIText != NULL) && ITEXTCTL_HandleEvent(pMe->m_pIText, EVT_KEY, wParam, dwParam)) {//Event handled by text controlreturn TRUE;}

if(pMe->m_pISoftKey != NULL && IMENUCTL_HandleEvent(pMe->m_pISoftKey, EVT_KEY, wParam, dwParam)) {//Event handled by menu controlreturn TRUE;}

14

return FALSE;

f. How can I get the capital/lowercase properties for a IText Control? Applicable Releases: 1.0, 1.1, 2.0 There is no API to determine the case of the text control string. You can convert the entire string entered to upper or lower case by extracting the text control string, calling WSTRUPPER() or WSTRLOWER() helper functions, and resetting the text control string.

g. How do I suppress the title area from showing on my IStatic? Applicable Releases: 1.0, 1.1, 2.0 The title area cannot be suppressed in SDK version 1.0. In SDK 1.1 onwards, supplying a NULL title prevents the title area from displaying.

h. How can I enable manual scrolling for my IStatic Control? Applicable Releases: 1.0, 1.1, 2.0 Manual scrolling of IStatic control is supported in BREW SDK™ 1.1 onwards. You can enable manual scrolling of the ISTATIC Control by following the steps below:

1) Use the ISTATIC_SetProperties() function with ST_NOSCROLL property2) Use the ISTATIC_HandleEvent() function in the EVT_ KEY case of your applications' HandleEvent function which processes the UP/DOWN key events for scrolling the text.

i. How do I set the background color of a IStatic control? Applicable Releases: 1.0, 1.1, 2.0 Changing the background color of an IStatic does not work as expected in all of the current SDK versions. When IDISPLAY_SetColor (display, CLR_USER_BACKGROUND, rgbValue) is used to set the background color of a ISTATIC control, the following behavior is seen:

1) When the ISTATIC control is in the Manual Scroll mode (for 1.1 and 2.0 only): The background color is not set.2) When the ISTATIC control is in the Auto Scroll mode (for all versions): The background color is set with the first auto scrolling movement.

This will be fixed in an upcoming version of BREW.

Creating BREW™ Applications

Compiling BREW Applicationsa. What compilers can be used to compile BREW applications for the target device?

Applicable Releases: 1.0, 1.1, 2.0 The RealView™ Compilation Tools for BREW and the ARM Compiler (of which the RealView Compilation Tools for BREW is a subset) can be used to compile BREW applications.

15

The GNU compiler is also available, but not officially supported. You can find more information on building the compiler, and download the required tools using the following link: https://brewx.qualcomm.com/developer/extranet/support/devtools.jsp#gcc

b. What compiler can be used to compile BREW applications for the Emulator? Applicable Releases: 1.0, 1.1, 2.0 Any compiler that can generate a Windows DLL can be used to compile BREW applications for BREW Emulator.

c. How do I compile an application to run on the handset? Applicable Releases: 1.0, 1.1, 2.0 To build applications for the phone requires the RealView™ Compilation Tools for BREW, which is used to compile and link a project that has been developed using the PC-based BREW SDK™, and related tools. Running an application built using the ARM tools requires a BREW-enabled phone, a data cable for establishing a serial connection to the phone, and file copying software such as QUALCOMM's BREW AppLoader application.

See How to Build a Downloadable BREW Application for more details.

d. What guidelines should be used when compiling applications in Thumb mode? Applicable Releases: 1.0, 1.1, 2.0 1. The function AEEMod_Load() must be moved to a different source file and this file must be compiled in ARM mode. AEEMod_Load() must always be compiled in ARM mode.

2. All files that are compiled in thumb mode MUST have the INTERWORK compiler option turned on. If this option is NOT turned on in the make file, then the app will very likely crash.

e. Are there any recommended steps to perform when installing the RealView™ Compilation Tools for BREW or ARM Development Suite? When you install the ARM compiler on your machine, consider installing it to a folder without spaces in the names. It makes it a lot easier to use the compiler on the command line.

Also, you might want to install it to 'c:\ads', as that seems to be the location where some things (like makefiles) default it to be. You can modify the makefiles to point to where you want it, but it's easier not to have to do that.

For more tips, please refer to How to Build a Downloadable BREW Application.

f. What should I do if I install the ARM compiler into a path with spaces?

16

Applicable Releases: 1.0, 1.1, 2.0 The solution is to modify your makefile in the following fashion: 1) Comment out the ARMBIN, ARMINC, and ARMLIB declaration. 2) Add the full path to the ARMCC, LD, and HEXTOOL variables. Make sure you double quote the path.

g. What is the latest release of the RealView™ Compilation Tools for BREW and where can I obtain maintenance patches, if any? Applicable Releases: 1.0, 1.1, 2.0 The latest version is the RealView™ Compilation Tools for BREW. This version, which is a free upgrade to developers who have already purchased ARM BREW Builder 1.0, is required to support Windows XP.

ARM BREW Builder 1.0 is based on Arm Developer Suite (ADS) 1.1. Since the release of the ARM BREW Builder 1.0, a maintenance patch for armlink (build 725) has been released. This patch can be downloaded at http://www.arm.com/support.nsf/html/downloads-ads11.

h. What flags should I set when compiling BREW applications to prevent static and global data from being linked into my application? Applicable Releases: 1.0, 1.1, 2.0 Make sure that the following flags are added to your make file. These flags will prevent global or static data from being linked into your application.

#ARM Procedure Call Standard OptionsAPCS = -apcs /$(ROPI)/$(INTERWRK)/norwpi

#Linker flagLFLAGS = $(ROPILINK) -rwpi

$(ROPI) flag is for Read-Only(code) Position independence$(INTERWRK) is to allow ARM-Thumb interworking$(ROPILINK) is to link image as Read-Only Position Independent

ARM 1.0 had these flags set by default, but removed this setting in 1.1. The 1.2 ADS (the basis of the RealView™ Compilation Tools for BREW) has reverted to the 1.0 style, so the setting of the above flags is only needed with the 1.1 ADS.

i. Does the ARM Compiler support exception handling? Applicable Releases: 1.0, 1.1, 2.0 No, the RealView™ Compilation Tools for BREW and the ARM Compiler (of which the RealView Compilation Tools for BREW is a subset) do not support try/catch or exception handling.

j. What guidelines should I follow when building the GNU compiler?

17

Applicable Releases: 1.0, 1.1, 2.0 When building the tool chain the most important thing is to keep other libraries out of your build. To do this you need to make sure that your path picks up first form your compiled directories before anything else. Common errors include unresolved external or undefined reference to `___mempcpy'. Such errors are discussed on the BREW forum. Because we are not officially supporting the tool we have created a GNU Forum for developers to share knowledge on how to build the tool and what issues they may have run into. QUALCOMM is monitoring the list and contributing as well.

Debugging BREW Applicationsa. How do I debug output on the emulator and on the handset?

Applicable Releases: 1.0, 1.1, 2.0 DBGPRINTF can be used to display debug messages on both the emulator and the phone. When debugging BREW applications on the emulator, DBGPRINTF outputs messages to the Visual C++ Debug Window.

To use DBGPRINTF to debug on the handset, you need to use the BREW Logger. The BREW Logger (included in the 2.0 Tools Suite onwards) is a tool that allows you to output debug messages to a PC over a serial connection. The debug messages can be viewed while the application is running and can be logged to a file. For more information on the BREW Logger, please refer to BREW 2.0 Tools documentation. Please also refer to the API User Guide entry on DBGPRINTF() for information on log message size restrictions.

b. How can I emulate the device characteristics on the emulator? Applicable Releases: 1.0, 1.1, 2.0 The device configurator file (.qsc) can be modified to emulate the device characteristics. Please refer to the Device Configurator Guide included in the SDK documentation.

c. How do I test my applications on the Emulator to determine if it behaves properly under low memory condition? Applicable Releases: 1.0, 1.1, 2.0 This can be achieved by reducing the heap size in the device configurator file (.qsc file) to almost the size of the .mod file. Any run time allocations by the applications should fail and you can test if your application deals with those failures correctly.

Since the size of the mod file a is a lot less then the dll that runs in the emulator, the emulator approximates the size of the mod file to be 10% of dll.

To properly run this test, create a separate directory that contains only the MIF of the application under test and have emulator point to this new directory (File->Change MIF Dir).

d. How do I test my application for EFS Full, Max Files Testing conditions on the Emulator?

18

Applicable Releases: 1.0, 1.1, 2.0 You can test your application's behavior under "EFS full" conditions and/or "Maximum File Limit reached" conditions on the emulator by modifying the device configurator file (.qsc file). Please refer to the Device Configurator Guide for details.

When performing this testing, please ensure that only application files are present under the application directory. That is, the application directory should contain only the .dll, .sig, .bar and other application specific files, and not the .c/.h , intermediate files, etc. Any file/directory present under the application directory is counted under the file count for the application.

Any extensions used by the application will also be counted towards the maximum file/space settings for the application. The emulator approximates the .mod file space to be around 10% of the .dll file size, and therefore 10% of the .dll is considered for the max space count.

If both the MIF file and the QSC file contain maximum file and space settings, then the settings in the MIF file take precedence over the settings in the QSC file. Please note that unless BOTH max file and max space settings are specified, the QSC file settings take precedence.

When an application has reached its max file count, calls to new file creation (i.e. IFILEMGR_OpenFile() with _OFM_CREATE parameter) will return NULL. Similarly, when an application has reached it max space count, calls to write function (IFILE_Write()) which increases the existing file size will also fail and return NULL.

e. Why do I get the following error when I try to launch my application? Error: " This application has been unloaded to save memory. You must download a new version". When see on the emulator, this message implies that the application dll is missing. Build your application using Visual C++ (Build->Rebuild All) before running it in the emulator.

When see on the phone, this message implies that the mod file cannot be found. If the app was downloaded using Mobile Shop, you can select 'Yes' to reload it. If the app was downloaded using the BREW App Loader, please make sure that you have downloaded the .mod file

f. Why does the Emulator display a blank screen with my application's name on it when my application exits? Applicable Releases: 1.0, 1.1, 2.0 Problem: When an application exits while running on the emulator, instead of returning to the main menu screen, a blank screen is displayed with the application name in the upper left corner.

19

This behavior is caused by not freeing all allocated memory before exiting the application. Any buffer you allocate using MALLOC or IHEAP_Malloc() must be freed using FREE or IHEAP_Free(). For any instance of a BREW class that you create, you must call the corresponding release function to free that instance.

g. Why do I get "Unknown Error (1)" when running my application? Applicable Releases: 1.0, 1.1, 2.0 This error generally occurs when there is a mismatch in the Class ID specified in the .mif file and the Class ID in the application code. If the following conditional evaluates to false, you will see this error (both on the emulator and on the phone):

int AEEClsCreateInstance(AEECLSID ClsId, Ishell* pIShell, Imodule* po, void** ppObj) {**ppObj = NULL;

if (ClsId == AEECLSID_MYAPP) { //has to be true in order to proceed// AEECLSID_MYAPP value is contained in the .bid file???}???br> }

Make sure that the Class ID in the .mif file is the same as the Class ID in the .bid file. Please note that you can use the MIF Editor to generate a Class ID locally for test purposes.

h. How can I debug network applications? Applicable Releases: 1.0, 1.1, 2.0 The Net Debug Tool can be used to view the device's network (socket and PPP) states while your application is running. When the Net Debug Tool is turned on, a box will appear in the right hand corner and will display a series of codes that can be used to determine the state of your application's data call. The codes vary per BREW version and are shown below.

The key sequence to turn on the Net Debug Tool is OEM dependent, and unless otherwise stated, is ###2 for all devices. To turn on the Net Debug tool, press ###2 from the BREW Application Manager Screen. To turn the Net Debug tool off, press ###0 from the BREW Application Manager Screen.

Network State Codes:

BREW 1.0:'c' Socket Connecting'C' Socket Connected'x' Socket Closing

20

' ' Socket Closed'I' Socket Idle'R' Socket Read'W' Socket Write'd' PPP Opening'D' PPP Open'-' PPP Closing'O' PPP Closed

BREW 1.1:'c' Socket Connecting 'C' Socket Connected 'x' Socket Closing 'X' Socket Closed 'I' Socket Idle 'R' Socket Read 'W' Socket Write 'r' Socket RecvFrom 'w' Socket SendTo'd' PPP Opening'D' PPP Open 'z' PPP Closing 'Z' PPP Closed

BREW 2.0:'c' Socket Connecting'C' Socket Connected 'x' Socket Closing'X' Socket Closed 'I' Socket Idle 'b' Socket Bind'B' Socket Bound'R' Socket Read 'W' Socket Write 'r' Socket RecvFrom 'w' Socket SendTo'^' PPP Opening'=' PPP Open'v' PPP Closing'#' PPP Closed'<' PPP Sleeping'~' PPP Asleep'>' PPP Waking

21

i. How can I debug my application to determine if its memory consumption is within the limits imposed by the handset's available memory? Applicable Releases: 1.0, 1.1, 2.0 The Debug Avail Memory Tool can be used to determine the largest free block of RAM available. When the Debug Avail Memory Tool is turned on, a box will appear in the left hand corner and will the largest free block of RAM available.

The key sequence to turn on the Debug Avail Memory Tool is OEM dependent, and unless otherwise stated, is ###2 for all devices. To turn on the Debug Avail Memory tool, press ###3 from the BREW Application Manager Screen. To turn the Debug Avail Memory tool off, press ###0 from the BREW Application Manager Screen.

j. How do I recover the phone from an "Undef Inst Exception"? Applicable Releases: 1.0, 1.1, 2.0 "Undef Inst Exception" stands for "Undefined instruction exception," and means that the program pointer has jumped to a code segment that contains an undefined instruction. This can be the result of memory corruption, a stack overrun, or version-related incompatibilities between applet code and the BREW image on the phone.

Memory is tighter on the phone than when running on the emulator. Therefore, memory and stack overrun problems will be more likely to show up on the phone. You should double check memory related areas of your code, especially auto variable arrays and the maximum total size of allocated memory.

To clear the phone, pull the battery out for a few seconds.

For more information on memory management, please refer to the following Knowledge Base articles: Stack Usage and Memory Allocation.

k. What is "Re-entrant Data Abort"? Applicable Releases: 1.0, 1.1, 2.0 The "Re-entrant Data Abort" exception is often caused by stack overrun. When an applet is running on the phone the stack size is small, and you are more likely to see stack overrun problems than when running on the emulator. Solutions to this problem are reducing the size or number of objects on the stack, and using objects allocated on the heap instead of automatic variables.

It has been reported that version-related incompatibilities between applet code and the BREW image on the phone can also lead to this type of exception.

For more information on memory management, please refer to the following Knowledge Base articles: Stack Usage and Memory Allocation.

22

l. What is "Pref Abort Exception"? Applicable Releases: 1.0, 1.1, 2.0 A "Pref Abort Exception" usually indicates that memory important to the phone operating system has been trashed. The two most common causes of this exception are data corruption (i.e. running off the end of an array), and stack overruns.

For more information on memory management, please refer to the following Knowledge Base articles: Stack Usage and Memory Allocation.

m. What is "SWI Exception"? Applicable Releases: 1.0, 1.1, 2.0 An "SWI Exception" is usually related to heap memory mismanagement. The most common causes of heap memory corruption are: overwriting the bounds of your allocated arrays, freeing objects more than once, and writing to wild or NULL pointers.

In addition to the more common causes, stack overrun can also lead to SWI Exceptions. It is recommended that large buffers be allocated on the heap rather than on the stack as automatic variables.

For more information on memory management, please refer to the following Knowledge Base articles: Stack Usage and Memory Allocation.

n. Why do I get "Application Digital Signature Failure 1054" when I try to launch my application? Applicable Releases: 1.0, 1.1, 2.0 Application Digital Signature Failure 1054 is indicative of the handset not having enough memory to load the app and do digital signature verification. This is usually a result of memory fragmentation. If this occurs, you will need to power cycle the phone and then run the application.

o. Why do I get "Application Digital Signature Failure 1030" when I try to launch my application? Applicable Releases: 1.0, 1.1, 2.0 Application Digital Signature Failure 1030 error code corresponds to invalid ESN number. You should verify that you are using the correct ESN number to generate the sig.

p. What is "Application Digital Signature Failure 1028"? Applicable Releases: 1.0, 1.1, 2.0 Application Digital Signature Failure Error #1028 corresponds to an expired Signature file (.sig). Signature files expire 90 days after they are generated. To generate a new signature file, use the Test Sig Generator.

q. Why do my log messages (logged using DBGPRINTF) get truncated?

23

Applicable Releases: 1.0, 1.1, 2.0 BREWLogger only permits logging messages with a maximum of 63 bytes. Anything above this limit will be truncated. For more information, please refer to the API User Guide entry on DBGPRINTF().

Localizing BREW Applicationsa. How does BREW deal with localizing applications for different languages? Applicable Releases: 1.0, 1.1, 2.0 a. We recommend that you make use of the resource file for anything that contains language (Bitmaps, Strings, and Dialogs) and load the required item as is needed in the program. This way you can avoid hard-coded items in your source, make separate resource files per language and not have to modify or recompile your sources.

Please refer to How do I display Korean strings on the Emulator and on the handset FAQ for more information on localizing apps in Korean.

b. How do I display Korean strings on the Emulator and on the handset? Applicable Releases: 1.0, 1.1, 2.0 b. On Korean BREW handsets that are currently available, the language is always set to Korean and the font is KSC5601. You can change it using these steps.

To set the language and font to be displayed on the Emulator 1. Run the BREW Device Configurator, and open the QSC file for the device you are

using (File > Open). 2. Click the Details button, to the right of the Model field, to show the Device Attributes

dialog box. 3. Proceed to one of the following sections and complete the procedure, depending on

the version of BREW SDK™ you are using.

For BREW SDK 1.0:

1. Do one of the following: o For Korean KSC5601, choose Korean from the Language drop-down list. o For Korean Unicode, choose Korean or English from the Language drop-

down list. 2. In the Normal and Large Font fields, click Set and select the Korean font and point

size you want to use. 3. Click OK.

For BREW SDK 1.1: 1. Click the Language & Fonts tab. 2. Do one of the following:

o For Korean KSC5601, choose Korean from the Language drop-down list, and KSC5601 from the Encoding drop-down list.

24

o For Korean Unicode, choose Korean or English from the Language drop-down list, and Unicode from the Encoding drop-down list.

3. In the Normal and Large Font fields, click Set and select the Korean font and point size you want to use.

4. Click OK.

Displaying text on the handset

You need to use IDISPLAY_DrawText() with the AEEChar string. The following procedures explain the changes you need to make in the BREW Resource Editor and in your C/C++ source code to create the AECHAR string using the KSC5601 and Unicode formats.

To display Korean strings using KSC5601 format 1. Launch the BREW Resource Editor. 2. Right-click the String icon, and choose New String. The String Resource dialog box

opens. 3. In the Resource Name field, type an ID, such as IDS_STRING_KSC. 4. From the String Format drop-down list, choose KSC5601. 5. In the Value field, type a string of Korean text. 6. Click OK. 7. Make the following changes in your C/C++ source code:

o Use ISHELL_LoadResString to load the string. **Sample Code**

AECHAR szBuf[30] = {0}; ISHELL_LoadResString(pMe->a.m_pIShell, APP_RES_FILE, IDS_STRING_KSC, szBuf, sizeof(szBuf)); IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL, szBuf, -1, pMe->m_cxWidth/5, pMe->m_cyHeight/8, 0, 0);

o Enter the normal character (unsigned char) string with the KSC5601 code. o Use the STR_EXPAND() to convert the normal character string to the

AEEChar string. **Sample Code**

AECHAR szBuf[30] ; const unsigned char szhello[] =""; STREXPAND(szhello,10,szBuf,30); IDISPLAY_DrawText(pMe->m_pIDisplay, AEE_FONT_BOLD, (AECHAR *) szBuf, -1, 0, 0, 0, IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE);

To display Korean strings using Unicode format 1. Launch the BREW Resource Editor.

25

2. Right-click the String icon, and choose New String. The String Resource dialog box opens.

3. In the Resource Name field, type an ID, such as IDS_STRING_UNI. 4. From the String Format drop-down list, choose Unicode. 5. In the Value field, type a string of Korean text. 6. Click OK. 7. Make the following changes in your C/C++ source code:

o Use ISHELL_LoadResString to load the string. **Sample Code**

AECHAR szBuf[30] = {0}; ISHELL_LoadResString(pMe->a.m_pIShell, APP_RES_FILE, IDS_STRING_UNI,szBuf, sizeof (szBuf)); IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL, szBuf, -1, pMe->m_cxWidth/5, pMe->m_cyHeight/8, 0, 0);

o Enter the AEEChar string with the Korean Unicode. You would need to enter the correct Unicode because Korean Windows would use KSC5601 for Korean text input. OR

o Convert [KSC5601 code Korean character (unsigned char) string] to [Unicode Korean AEEChar string] using the KSC5601 to Unicode conversion. This method is not recommended because it requires too much memory on the BREW handset. **Sample Code**

AECHAR szBuf[30] ; const unsigned char szhello[] =""; STREXPAND(szhello,10,szBuf,30); IDISPLAY_DrawText(pMe->m_pIDisplay, AEE_FONT_BOLD, (AECHAR *) szBuf, -1, 0, 0, 0, IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE);

**STREXPAND() Sample Code**void STREXPAND(const byte * pSrc, int nCount, AECHAR * pDest, int nSize) Parameters: pSrc Null terminated source string nLen Length of the source string in chars pDest Pointer to the destination buffer nSize Size of the destination buffer in bytes

Operating Systems and Processorsa. What are the Operating Systems requirements of the BREW

26

SDK? Applicable Releases: 1.0, 1.1, 2.0 Due to the requirement for Unicode support, the SDK runs only on the Microsoft Windows NT™ 4.0, Windows 2000™ and Windows XP™ platforms. Windows 98 is not supported by the BREW SDK. Also, the Chinese, Japanese and Korean versions of the SDK are supported only on the corresponding language-version of Windows, so you must install the Chinese SDK, for instance, on Chinese Windows.

b. On what devices is BREW supported? Applicable Releases: 1.0, 1.1, 2.0 BREW is currently supported only on QUALCOMM MSM chipsets, but we expect that it in the future, BREW will be supported on non-Qualcomm chipsets as well. There is currently no announced time-frame for BREW support on chipsets other than QUALCOMM's MSM chipset series.

c. Is BREW available on non-QUALCOMM chipsets? Applicable Releases: 1.0, 1.1, 2.0 Yes, BREW is available on non-QUALCOMM chipsets. At 3GSM World Congress 2003 in February, QUALCOMM demonstrated applications based on BREW client running on a GSM/GPRS handset, the Maxon MX7830, which uses TTPCom's GSM/GPRS protocol stack. These demonstrations validate BREW as an air-interface-independent solution that provides value-added products and services to operators, developers and handset manufacturers worldwide.

BREW is available on the following MSM chipsets: MSM3100, MSM3300, MSM5000, MSM5100, MSM5105, MSM5500, MSM6050, MSM6100, MSM6200, MSM6250 and MSM6300.

Portabilitya. I have an application that was written using the 1.0.1.18 BREW

SDK. However, the version of the BREW API on my phone is 1.0.2.4. Will my application run on the phone? Applicable Releases: 1.0, 1.1, 2.0 Yes, it will run. BREW is designed to be forwards compatible, but is not guaranteed to be backwards compatible.

The following should be kept in mind when trying to determine compatibility between the version of the BREW SDK and the BREW API on the phone:

27

An application that is written for version X of the BREW SDK will work on a version X or a later version of the BREW API on the handset. However, the converse may not be true i.e. an application that is written for a version X of the BREW SDK may not work on a handset that has a version of the BREW API that is earlier than version X.

b. Are BREW apps portable across devices? Applicable Releases: 1.0, 1.1, 2.0 BREW applications can be made portable by adhering to the guidelines described at How to Build Portable BREW Applications.

Uploading BREW Applications to Handsetsa. How do I transfer compiled applications to the phone?

Applicable Releases: 1.0, 1.1, 2.0 Use BREW AppLoader to upload applications to the phone. The following example shows files and locations for an application with the name "myapp."

/brew/myapp.mif - Generated by BREW MIF Editor/brew/myapp/myapp.bar - Generated by BREW Resource Editor/brew/myapp/myapp.mod - Compiled and linked with ARM Developer Suite/brew/myapp/myapp.sig - Digital Signature

All directory and file names on the phone must be in lower case. Any additional files specific to your application may also be copied to the application directory, or subdirectories of the application directory.

The Digital Signature file is generated using the BREW TestSig Generator then renamed with the name of the application. The name of the .sig filename must be the same as the name of the .mod filename. The application directory name should be same as name of the MIF file.

In order to use a test-signature file on your handset, your handset must be test-enabled. This is done as a security measure. If a test signature is loaded on a handset that is not test-enabled, BREW will remove the application from the handset. To get your handset test-enabled, please send it to the QIS Phone Center. For more information, please refer to Where should I send my phone when it needs to be re-flashed, or have DNS configured or test-bit enabled?.

After uploading files, reset the phone.

See How to Build a Downloadable BREW Application for more details.

28

b. How do I upload the device configurator (.qsc) file to the phone? Applicable Releases: 1.0, 1.1, 2.0 The device configurator file (.qsc) is used by the BREW Emulator application, and is not required to run applications on the phone.

Writing BREW Codea. What steps should I follow to create a BREW application? Applicable Releases: 1.0, 1.1, 2.0 Please refer to the Knowledge Base article How to create BREW Applications for more information.

b. My newly created application does not appear when I launch the Emulator. Why? Applicable Releases: 1.0, 1.1, 2.0 Please ensure that 1) The application DLL is present under the application directory (BREW\Examples\appName\appName.dll). When creating an application using BREW Application Wizard, the Project Settings are set such that the application DLL is created under \debug or \release. You should modify this such that the DLL s created under the application directory. Please refer to Step 6 of How to Create BREW Applications. 2) The application MIF file is present under the Examples directory (\BREW\Examples\appName.mif).

c. Is it possible to have static/global data in my app? Applicable Releases: 1.0, 1.1, 2.0 You cannot have static/global data in your dynamically loaded application. This can be emulated by using the Applet data structure. Please refer to What flags should I set when compiling BREW applications to prevent static and global data from being linked into my application? FAQ if you are using ARM ADS version 1.1.

d. What should I be careful about when developing BREW applications using C++? Applicable Releases: 1.0, 1.1, 2.0 For an application to be dynamically loadable on the handset, it should be position-independent and hence must not have any global data. When you do "new" on a class, the ARM compiler includes some header files that bring in global data. You should overload the new and delete operators in each class, and inside the implementation of those overloaded operators use the AEEStdlib functions MALLOC and FREE, respectively. You should also Override new[] and free[].

Here is an example:

void *operator new ( size_t size) {return MALLOC (size) ;}

29

void operator delete(void * ptr) {FREE(ptr) ;}

You won't be able to use the C++ virtual function or inheritance mechanisms to derive from existing BREW classes. For example, you can't define a class called CApplet and have it derive from the IApplet interface. We are working on overcoming this limitation.

What you can do in C++ is define your applet's data as a class. For example, instead of defining a struct called CMyApp that contains all the app-specific data, you can make it into a class. You can continue to pass its size to AEEApplet_New. What will be passed back to you in the HandleEvent (and other) functions will be a pointer to your C++ object, which you can then use in the C++ means.

e. Does BREW support multi-threading? Currently, BREW does not support multi-threading. BREW does have support for cooperative multi-tasking. Please refer to ISHELL_Resume() for information on cooperative multi-tasking.

f. What Java development options exist for BREW? Applicable Releases: 1.0, 1.1, 2.0 The JAVA Virtual Machine (JVM) is being implemented as a BREW extension by vendors such as IBM and Insignia. A BREW extension is a downloadable software layer that runs on top of BREW and offers value added functionality. Examples include XML parser, JVM.

BREW applications can be created in Java for handsets that support BREW 2.0 and above.

Java applications can be written for BREW enabled devices by using a BREW SDK with Java support (Java support will be made available shortly). The J2BRIDGE tool can then be used to create ARM executable file (.mod) and the Module Information File (.mif) that are required by BREW.

g. What should I be careful about when using Assembler? Applicable Releases: 1.0, 1.1, 2.0 You should be careful with branch instructions, i.e. a long branch from within your code to outside the module. Anything outside your code branch should use registers. Also, as usual, you should have no global or static data. Please see the ARM Users Guide for more information on mixing inline ARM and C code. This will explain fully how ARM will arrange registers when compiling C code.

h. Can I link to Windows DLLs from the BREW SDK? Applicable Releases: 1.0, 1.1, 2.0 No. You should treat the SDK as a fully integrated stand-alone platform, which includes avoiding the C Standard Libraries. BREW has provided a port of the most common functions.

30

i. How do I create portable BREW applications that will run across devices? Applicable Releases: 1.0, 1.1, 2.0 Please refer to "KB: How to Build Portable BREW Applications" for more information.

j. How do I obtain a class ID for my BREW application? Applicable Releases: 1.0, 1.1, 2.0 Prior to submitting your BREW application for True BREW Testing, you must obtain official BREW Class IDs using the BREW Class ID Generator available via the web interface. In order to access this page, your company will have to purchase a BREW-specific digital certificate from VeriSign, Inc. and authorize specific developers to access this tool on the BREW Developer Extranet.

During application coding and testing (prior to submission), you may use the MIF Editor to generate a temporary Class ID (larger than 0x02000000).

k. How do I generate a test signature file? Applicable Releases: 1.0, 1.1, 2.0 To generate a test signature file, use the BREW TestSig Generator available on the BREW website (Developer extranet access required). Enter the phone's Electronic Serial number (ESN) in the following format: 0xaabcccdd.

Device Where to find theESN

Kyocera 3035 Label under battery

Sharp Z-800 Main Menu-> Display-> Version

LG VX-10 Label under battery

Motorola T-720 Main Menu-> Settings-> Phone Status-> Other Information-> ESN

Toshiba CDM-9500 Label under battery

LG VX-4400 Label under battery

Samsung A-530 Label under battery

Samsung A-561 Label under battery

Kyocera 3225 Label under battery

For example: On the Kyocera 3035, the ESN can be found by removing the battery and looking at the label on the backside of the phone. The ESN is pre-fixed by 'H:'. The ESN on the phone below is FEDA6548, and needs to be entered in as 0xFEDA6548 in the TestSig Generator.

31

l. The device I am targeting has BREW SDK 1.2, however I can't find a BREW 1.2 SDK. What SDK should I use to develop my BREW application? Applicable Releases: 1.2 An SDK was not released for BREW version 1.2. To develop for 1.2 handsets, you can either1) Use the 1.1 SDK or2) Use the 2.0 SDK, but be careful not to use 2.0 specific features during development.

BREW 1.2 adds support for the following features:IFontIBitmapBluetoothIClipboardIHTMLViewerMobile Originated SMS (MOSMS)ITAPI Enhancements

If your application needs to use any of the above features, you should use the 2.0 SDK for development. Please be careful about including any 2.0 specific features as it could cause unwanted behavior when actually run on the device. If you are not using any of the BREW 1.2 features, it would be safer to use the SDK 1.1 which has the bonus of being directly compatible with 1.1 handsets as well.

Additionally, please refer to the device data sheet to reference what features may not be supported by the particular OEM.

Event Handlinga. What events must an applet handle? Applicable Releases: 1.0, 1.1, 2.0 In addition to EVT_APP_START and EVT_APP_STOP, your applet must support EVT_APP_SUSPEND and EVT_APP_RESUME in order to pass TRUE BREW® Testing.

See Suspending and Resuming Applications for more information on Suspend and Resume

32

events, and What are the most common reasons why applications fail testing? for more information on Common Reasons why applications fail TRUE BREW Testing.

b. What is the difference between using the phone's "End" key and using the "Clear" key to close an application? Applicable Releases: 1.0, 1.1, 2.0 The OEM of a particular device (phone) designates key(s) for the following two activities:

A key, that when pressed, will close the current application. Most OEMs designate this to be the AVK_CLR key.

A key, that when pressed, will close all applications. Most OEMs designate this to be the AVK_END key.

When AVK_END is pressed, BREW™ will immediately send EVT_APP_STOP to the active applet without first sending the AVK_END key. The applet will be released and the FreeAppData() callback routine provided to AEEApplet_New() will be called prior to unloading the applet.

When AVK_CLR is pressed, BREW will first send this event to the applet. If the applet does not handle the event (i.e. returns FALSE in HandleEvent), only then BREW will close the application. In the implementation of your AVK_CLR handler, you should do as follows:

case AVK_CLR:if (pMe->OnMainMenu == TRUE) {// App is on main menu. Pressing CLR key should cause app to exitreturn FALSE; //return FALSE so that BREW will now close app}else { // Not on main menu. // Pressing CLR key should cause app to undo one level of menu nesting. // Show previous menu in menu hierarchyreturn TRUE;}

Make sure that your FreeAppletData() properly cleans up all allocated memory and resources. All objects and interfaces created by CreateInstance, CreateDialog, MALLOC, etc., must have an associated call to Release or FREE.

c. How should I handle Suspend/Resume events? Applicable Releases: 1.0, 1.1, 2.0 Please refer to Suspending and Resuming Applications.

d. How do I deal with low battery warning? Applicable Releases: 1.0, 1.1, 2.0 BREW sends the running application an EVT_APP_SUSPEND event in the case of a Low Battery Warning. In order to handle low battery condition, you must correctly handle

33

EVT_APP_SUSPEND and EVT_APP_RESUME events.

See Suspending and Resuming Applications for more information on Suspend and Resume events.

e. What is the difference between ISHELL_SendEvent() and ISHELL_PostEvent()? ISHELL_SendEvent() and ISHELL_PostEvent() functions are both used to send an event to a specified class. The difference between the two lies in the manner in which the event is sent.

In the case of ISHELL_SendEvent(), the event is immediately sent to the application of the specified Class ID. If an instance of that class is not currently present, the AEE Shell creates one, and then invokes its IAPPLET_HandleEvent() function with the specified event code and data parameters. Unless it chooses to start itself, the application terminates after it completes processing of the event.

ISHELL_PostEvent() is similar, except that the destination class's IAPPLET_HandleEvent() function is not called immediately. The event is placed in a queue and is sent at a later time, which allows the calling application to continue its processing without interruption. Duplicate ISHELL_PostEvent messages will be discarded.

The ISHELL_SendEvent() function allows for control over the destination applet. This function sends the event directly to the destination applet. The processing of events posted using ISHELL_PostEvent() is deferred until the next iteration of the event loop. This is useful in providing continued execution while allowing other events to be processed.

Assume for the moment that the applet receiving the event (PostEvent/SendEvent) is not the currently running applet. In this situation, after the event is dispatched and routed to the receiving applet, the applet will be released and off-loaded unless

a) There are other pending events for the app orb) The app has tried to start itself or has tried to go to the background.

f. What system notification events can my app register for? Applicable Releases: 1.0, 1.1, 2.0 An app can register for the following System notifications:

TAPI (Class ID: 0x01001007)

NMASK_TAPI_STATUS 0x0001 TAPI Status change event

NMASK_TAPI_SMS_TEXT 0x0002 Incoming SMS

NMASK_TAPI_SMS_TS 0x0004 SMS message on specific

34

Teleservice ID

INETMGR

NMASK_OPENED 0x0001 Network layer is available

NMASK_CLOSED 0x0002 Network layer is closed

NMASK_IDLE 0x0004 Network layer available and idle (included in BREW SDK 1.1 and onwards)

ISHELL

NMASK_SHELL_INIT 0x0001 BREW is getting initialized (included in BREW 2.0 SDK and onwards)

Please note that 1) INETMGR NMASK_UDP_LISTEN has been deprecated and does not work. 2) There is a bug in BREW SDK 1.0 that precludes applications from registering for NMASK_TAPI_STATUS in the application's MIF file. For more details on this 1.0 bug (fixed in SDK 1.1), please refer to Registering for NMASK_TAPI_STATUS event notification causes device to be unable to connect to Application Download Server (ADS).

In BREW SDK 2.0 onwards, applications can register for the following system events using ISHELL_RegisterSystemCallback:

AEE_SCB_AEE_INIT BREW gets initialized

AEE_SCB_AEE_EXIT BREW exits

AEE_SCB_LOW_RAM Device RAM goes below a pre-set threshold

AEE_SCB_LOW_STORAGE Device storage goes below a pre-set threshold

AEE_SCB_APP_CLOSED Application is about to be closed

AEE_SCB_MOD_UNLOAD Module is about to be unloaded

g. How can I test my application for proper handling of Suspend/Resume events on a non-provisioned phone? Applicable Releases: 1.0, 1.1, 2.0 On phone without a clamshell, such as the Kyocera 3035, you can test your app's handling of Suspend/Resume events by enabling automatic Keyguard before running your app. When the Keyguard kicks in, the running app will receive a Suspend Event. The app will receive

35

Resume event when the screen is unlocked.

To set automatic Keyguard on the Kyocera 3035, use Main Menu->Settings->Keyguard.

On phones with a clamshell, such as the Sharp Z-800, you can test your app's handling of Suspend/Resume events by setting the alarm to go off a few minutes in the future and then running the BREW app.

On the Sharp Z-800, you can set alarms using Main Menu->Setup/Tools->Alarm->Daily Alarm. Please note that in order for the app to be suspended when the alarm goes off, BREW Priority Setting must be off (Main Menu->Setup/Tools->BREW Priority Setting).

h. What is "Preparing Applications"? Applicable Releases: 1.0, 1.1, 2.0 One of the functions of the BREW Core App is to send acknowledgements for newly downloaded apps and recently deleted apps to the Application Download Server (ADS). For example, when you delete an app through MobileShop, BREW maintains a record stating that the Delete Acknowledgement (ack) needs to be sent to the server. BREW tries to send the ack the next time you connect to MobileShop or the next time you power on the handset and start BREW (in the latter case, BREW starts the Core App to send the acknowledgements). The BREW Core App is started internally by BREW - the user can never start the Core App.

If there is an app running when the BREW internally starts the Core App, then the running app will be suspended. Therefore, an application does not need to do anything more than handle Suspend/Resume events (as detailed in Suspending and Resuming Applications), in order to correctly handle the "Preparing Applications" message.

Media

Display and Imagesa. What image formats are supported in BREW?

Applicable Releases: 1.0, 1.1, 2.0 BREW supports any BMP file with a color depth up to that which is provided on the device it is running on. BREW does not yet support GIF and JPEG images. Some devices may support GIF and JPEG images, please check the device data sheet to see if the OEM has provided an extension to support these or other formats. PNG format and BREW Compressed Image (BCI) format are supported in BREW SDK™ version 1.1 onwards. In SDK 2.0 onwards, IDIB is supported. Using IDIB will save you the call to CONVERTBMP and thus results in faster screen updates. WBMP will be supported in BREW SDK 2.1 onwards.

In BREW SDK 1.0, the emulator is capable of emulating only 1, 4, and 8-bit color depth BMPs. SDK 1.1 adds emulator support for 2-bit color depth, and the 2.0 SDK adds emulator support for 16-bit color depth BMPs.

36

b. How do I generate 2-bit images? Applicable Releases: 1.0, 1.1, 2.0 The 2 Bit Tool, included in the 2.0 SDK, can convert between 2 and 4 bit bitmaps. To construct 2-bit bitmaps for use with grayscale handsets, you can construct them in MS Paint with the white, black, light grey, and dark grey entries from the palette (they are usually the first 2 colors on the first and second rows). Save as a 16 color image and then use the 2Bit tool to convert it to a 2-bit bitmap.

c. What is the transparent color on color and monochrome phones? Applicable Releases: 1.0, 1.1, 2.0 In BREW 1.x, magenta is the transparent color for color devices and white is the transparent color on monochrome and 4-level gray devices. In BREW 2.0 onwards, the transparency color is changeable via IBITMAP_SetTransparencyColor. CONVERTBMP initializes the transparency color to be compatible with older versions of BREW (i.e. magenta and white). However there is no fixed transparency color for bitmaps obtained through other means.

d. How do I create an IIMAGE object from an in-memory bitmap? Applicable Releases: 1.0, 1.1, 2.0 Loading bitmaps as a resource, or from a file, is accomplished using the ISHELL interfaces ISHELL_LoadResImage (for resources) and ISHELL_LoadImage (for files). However, there are instances when it may be necessary to initialize an IIMAGE object from memory - when modifying a bitmap's contents prior to display, for instance, or retrieving an image via socket connection without first caching the data to a file.

In situations where it is necessary to initialize an IIMAGE object with an in-memory bitmap, the IIMAGE interface IIMAGE_SetStream should be used. The following code sample demonstrates this technique by calling ISHELL_GetHandler to obtain the Class ID of a BMP image handler, then creating a MemAStream object and using it as a stream to the in-memory bitmap. Note that in this example the image format is Windows BMP, with "pMe->pBmpData" pointing to the beginning of a Windows file-format BMP (BITMAPFILEHEADER).

Code Sample: AEECLSID cls;IImage *pIImage = NULL;IMemAStream *pMemStream = NULL;

// Determine the class ID of the handler function for BMPs and then// create an instance of this BREW classcls = ISHELL_GetHandler(pMe->a.m_pIShell, HTYPE_VIEWER, "image/bmp");

if (cls) {

37

ISHELL_CreateInstance(pMe->a.m_pIShell, cls, (void **)(&pIImage));}

if (pMe->pBmpData) {ISHELL_CreateInstance(pMe->a.m_pIShell, AEECLSID_MEMASTREAM, (void **)(&pMemStream));if (pMemStream) {//Create MEMSTREAM and use it as stream for the in-memory bitmap.IMEMASTREAM_Set(pMemStream, pMe->pBmpData, sizeof(pMe->pBmpData), 0, 0);IIMAGE_SetStream(pIImage, (IAStream*)pMemStream);

// use your IIMAGE methods as normal nowIIMAGE_Draw(pIImage, ? ?;IDISPLAY_UpdateEx(pMe->a.m_pIDisplay, TRUE);}}

e. How do I load images from a file or from a resource file? Loading and drawing images from files or resources is easily accomplished using the ISHELL interfaces ISHELL_LoadResImage (for resources) or ISHELL_LoadImage (for files), followed by IIMAGE_Draw. This article demonstrates the basic steps required to load and display bitmap images using the ISHELL and IIMAGE interfaces.

Steps for Displaying an Image from a resource: 1. Create your Bitmap 2. Add it into the Resource Editor 3. Compile .bar and .h files in the resource editor 4. Add the .h file to your project 5. Load the image using ISHELL_LoadResImage 6. Display the image using IIMAGE_Draw() 7. Update the screen with IDISPLAY_Update() Code Sample: #define MY_RES_FILE "Myres.bar"

// Load and display a bitmap from a resourceint MyDisplayResImage(){IImage *pImage = NULL;AEEDeviceInfo dm;// Get Device info, so we can see color depthISHELL_GetDeviceInfo(pShell, &dm);

// If it is greater color depth than 4 load color bitmapif( dm.nColorDepth > 4)

38

{// Load image from ResourcespImage = ISHELL_LoadResImage(pShell, MY_RES_FILE, IDB_MY_COLOR_BITMAP);}else{// Load image from ResourcespImage = ISHELL_LoadResImage(pShell, MY_RES_FILE, IDB_MY_BW_BITMAP);}

if( !pImage )return EFAILED; // Failed to load it

// Draw image at 0,0 coordinatesIIMAGE_Draw(pIImage, 0, 0);

// Update the screenIDISPLAY_Update(pDisplay);

// Free the IIMAGE objectIIMAGE_Release( pImage );

return SUCCESS;}

Steps for Displaying an Image from a file: 1. Load the image from file using ISHELL_LoadImage 2. Display the image using IIMAGE_Draw() 3. Update the screen with IDISPLAY_Update() Code Sample: // Load and display an image from a fileint MyDisplayFileImage(){IImage *pImage = NULL;AECHAR* pImageFile = NULL;AEEDeviceInfo dm;AECHAR szColorBmp[] = {'c','o','l','o','r','.','b','m','p'};AECHAR szBWBmp[] = {'m','o','n','o','.','b','m','p'};

// Get Device info, so we can see color depthISHELL_GetDeviceInfo(pShell, &dm);

39

// If it is greater color depth than 4 load color bitmapif( dm.nColorDepth > 4)pImageFile = szColorBmp;elsepImageFile = szBWBmp;

pImage = ISHELL_LoadImage(pShell, pImageFile);

if( !pImage )return EFAILED; // Failed to load it

// Draw image at 0,0 coordinatesIIMAGE_Draw(pIImage, 0, 0);

// Update the screenIDISPLAY_Update(pDisplay);

// Free the IIMAGE objectIIMAGE_Release( pImage );

return SUCCESS;}

f. Does BREW support animation? Applicable Releases: 1.0, 1.1, 2.0 BREW SDK version 1.0 includes support for animated BMP. This is done by placing the frames side-by-side and specifying the width of each frame with IIMAGE_SetParm with the IPARM-CXFRAME flag. Please see the IIMAGE example in the Examples directory.

BREW SDK Version 1.1 adds support for BREW Compressed Image (BCI) animation. A BCI file contains one or more compressed small graphic image(s), each with a specified duration in milliseconds. The duration represents how long you want each image to be shown before it is replaced by the next image in the series. You can use the BCI Authoring Tool included in BREW SDK Version 1.1 to create your BCI file. Please refer to 'Using the BREW Compressed Image Authoring Tool' document included in the SDK for more information.

BREW does not currently support animation of the PNG and MNG formats.

g. Why does all the animation slow down after a while? Applicable Releases: 1.0, 1.1, 2.0 Most OEM's implement a sleep timer. This controls when the device will go to sleep. If there is no key activity for a certain OEM-dependent period of time, the handset will go to

40

sleep. When the device is sleeping the frame rate will decrease excessively. Pressing a key will wake it up and will restore the previous frame rate.

In BREW 2.0, applications can choose whether or not to go to sleep. If the application returns TRUE when the EVT_APP_NO_SLEEP event is sent to it, then the application will not go to sleep. For example:

case EVT_APP_NO_SLEEP://Don't want to sleep return TRUE;

h. Is it possible to get/manipulate the palette information of the device? Applicable Releases: 1.0, 1.1, 2.0 No. The palettes are hard-coded by the vendor and will vary from device to device.

i. Can I modify the display buffers directly? Applicable Releases: 1.0, 1.1, 2.0 In BREW 1.x there is no way for to access these and the display data is stored in the vendor's proprietary format.

Starting with BREW 2.0, some bitmaps (such as the device bitmap) may support the IDIB interface if the pixel layout of the bitmap is compatible with the BREW device independent bitmap specification. The pixel buffer may be accessed through the pBmp member of the IDIB structure. To determine whether a bitmap supports IDIB and to obtain an IDIB pointer, you can use IBITMAP_QueryInterface with a class ID of AEECLSID_DIB.

j. Can I do off-screen rendering? Applicable Releases: 1.0, 1.1, 2.0 IDISPLAY_Set/GetDestination or IGRAPHICS_Set/GetDestination can be used to perform off-screen rendering. These functions are available in BREW version 1.2 onwards.

There is no 1.2 BREW SDK. To make use of BREW 1.2 features, you can use the 2.0 SDK when developing a 1.2-targeted app. You should be careful not to use 2.0 features that are not supported in 1.2. This list of features is documented at the FAQ, The device I am targeting has BREW SDK 1.2, however I can't find a BREW 1.2 SDK. What SDK should I use to develop my BREW application?.

The IGRAPHICS_EnableDoubleBuffer API, although present in the documentation, is not supported by any version of BREW.

k. How do I draw a line in a specific color? Applicable Releases: 1.0, 1.1, 2.0 IDISPLAY_DrawHLine() and IDISPLAY_DrawVLine() always draw lines in black.

41

Therefore setting CLR_USER_LINE to the desired color and then invoking IDISPLAY_DrawHLine() or IDISPLAY_DrawVLine() will not work.

The definitions of these two IDISPLAY macros are below. To draw a line in a color other than black, use the code contained in the macro definition and change to the desired fill color.

#define IDISPLAY_DrawHLine(p,x,y,len) \{AEERect rc;SETAEERECT(&rc,(x),(y),(len),1); IDISPLAY_FillRect((p),&rc, RGB_BLACK);}

#define IDISPLAY_DrawVLine(p,x,y,len) \{AEERect rc;SETAEERECT(&rc,(x),(y),1,(len)); IDISPLAY_FillRect((p),&rc, RGB_BLACK);}

l. How do I determine the character limit for the display of application names on the phone? Applicable Releases: 1.0, 1.1, 2.0 Different phones have different display characteristics, so there is no unique answer to this question. You can determine whether your application name will fit on the phone's display by comparing the width of the application name to the width of the display.

Use IDISPLAY_MeasureText() to determine the pixel width of your application name string. Use ISHELL_GetDeviceInfo() to determine the pixel width of the screen.

m. How do I save images to the phone's wallpaper directory? Applicable Releases: 1.0, 1.1, 2.0 Although the current SDK does not include a Wallpaper API, some OEMs support saving images to the native UI's Wallpaper directory by means of the Shared content directory.

You can create/download an image into the shared directory using the following code snippet:

// Please note that for this code to work, the application must have the // "Access to Shared Directory" and "File" privileges in the MIF file.STRCAT( filename, AEE_SHARED_DIR );STRCAT( filename, "/" );STRCAT( filename, "test.gif" );IFILEMGR_OpenFile( m_pIFileMgr, filename, _OFM_CREATE );

AEE_SHARED_DIR is OEM-defined and maps to the specific shared directory path on each device. If the OEM supports saving images to the Wallpaper directory, then an image saved in AEE_SHARED_DIR will appear in the native UI's Wallpaper directory. To see whether a particular handset supports wallpaper images via the Shared directory and

42

the image types supported, please refer to the handset's Device Data Sheet.

There is currently no BREW API that allows setting of a particular image as the wallpaper for the handset. This must be done through the native UI.

n. Why do I get memory errors such as "memheap.c 0696" when using IDISPLAY_BitBlt() to draw a bitmap image? Applicable Releases: 1.0, 1.1, 2.0 Please ensure that you are freeing the memory allocated by CONVERTBMP. Check the last Boolean parameter of CONVERTBMP. If True, a reallocation was done and the memory must be freed using SYSFREE.

For example:pBmp = CONVERTBMP (pDataBytes, &imageInfo, &bVal);IDISPLAY_BitBlt (pIDisplay, xDest, yDest, cxDest, cyDest, pBmp,xSrc, ySrc, dwRopCode);

IDISPLAY_Update (pIDisplay);

if(bVal) //free only if realloc was doneSYSFREE (pBmp);

Please refer to the description of the CONVERTBMP helper function in the API Reference Document. For example code, you can refer to the IDisplay Usage example.

o. Why are fewer colors being displayed than expected on the Emulator? Applicable Releases: 1.0, 1.1, 2.0 If you are getting a low-resolution display for a 16bit image on the 2.0 emulator, check the device attributes using the Device Configurator and set the Color Depth to 16 bit. If you are still getting a poor resolution (for an 8 bit or 16 bit), check if you have used the IIMAGE_SetParm() function to set improper parameters for the image to be displayed.

p. Why aren't some PNG images displayed correctly? Applicable Releases: 1.0, 1.1, 2.0 Two things need to be considered when using PNG with BREW. 1) Alpha channels are not supported in versions 1.0, 1.1 and 2.0, but should be for the 3.0 SDK release. 2) BREW handles PNG transparency by taking only the first transparent color in the file. All other colors are displayed. Check your file to ensure that you have created only one transparency color.

q. Why does PNG image creation result in the memory usage far larger than the actual size of the image? Applicable Releases: 1.0, 1.1, 2.0

43

When a BREW app loads a PNG image using ISHELL_LoadResData, a large amount of additional space is required to decode the image. As an example, to load a 217-byte PNG image 45,177 bytes are required.

Sounda. ISoundPlayer doesn't seem to work on my device. Why?

Applicable Releases: 1.0, 1.1, 2.0 Using the ISoundPlayer interface requires Multimedia support (QUALCOMM's Compact Multimedia Extension - CMX, or equivalent) on the device. For example, the Kyocera 3035 is not CMX-enabled and does not support ISoundPlayer interface.

b. How do I play a rest period (silent tone) in my tone sequence?Applicable Releases: 1.0, 1.1, 2.0 In BREW SDK™ versions 1.1 onwards, the AEESoundTone AEE_TONE_SILENCE can be used to play a silent tone. In BREW SDK version 1.0, there is no support for playing a silent tone. If using SDK 1.0, you can choose a tone that sounds close to silent, or just stop playing for a moment and resume.

c. ISOUND_Vibrate doesn't seem to work on my phone. Why? Applicable Releases: 1.0, 1.1, 2.0 OEM Support is required for this feature. The OEM is not required to implement this feature.

d. Does BREW support the playing of MP3s? Applicable Releases: 1.0, 1.1, 2.0 Yes, BREW supports playing MP3 files through the ISoundPlayer interface, as long as the device's chipset and overlying multimedia layer (CMX or equivalent) with MP3 decoder are present.

For more information on the capabilities of the different devices, see Phone Details.

e. Which MIDI formats are supported by BREW? Applicable Releases: 1.0, 1.1, 2.0 MIDI formats SMF0 (Standard MIDI Format) and SMF1 are supported by all versions of BREW.

f. Can WAV files be played in BREW? How can I create a file with QCP format? Applicable Releases: 1.0, 1.1, 2.0 BREW versions 1.0, 1.1 and 2.0 do not support playback of the WAV format. The PureVoice Convertor Utility Tool provided with BREW SDK versions 1.1 onwards can be used to convert .WAV to .QCP and vice-versa.

g. Does BREW Support the PMD format? Applicable Releases: 1.0, 1.1, 2.0

44

PMD files contain audio and/or video. BREW 2.0 is capable of playing audio+video PMD files. BREW 1.0 and 1.1 are capable of playing only audio files. OEM support is required to play PMD files on a device.

h. Where can I get more information about CMX? Applicable Releases: 1.0, 1.1, 2.0 Please visit the following link: http://www.cdmatech.com/solutions/pdf/cmx_faq.pdf. To play CMX files on the emulator, you will need to install the CMX player (available on the Developer Extranet under Developer Tools).

i. Where can I get more information about Yamaha's MMF format? Applicable Releases: All For more information on Yamaha's SMAF format (.mmf files) please refer to http://smaf-yamaha.com

j. Can I emulate the playback of Yamaha's SMAF format in the BREW SDK? Applicable Releases: 2.1 SMAF playback can be emulated in the BREW 2.1 SDK. In order to enable this you first need to download the SMAF emulation component from http://smaf-yamaha.com/brew/, then copy the downloaded files to the following directories:

ma3smwemu.dll to $BREWDIR\bin\ModulesJazz35s.mid and Jazz35s.mmf to $BREWDIR\bin\DataFiles

(where $BREWDIR is your BREW SDK 2.1 root directory)

k. Why do I get a memory leak error while using ISOUNDPLAYER? Applicable Releases: 1.0, 1.1, 2.0 In BREW versions 1.1 and 2.0, the call to ISOUNDPLAYER_SetInfo() allocates some memory internally for the file name (if playing from a file) or buffer(if playing from a buffer). This memory has to be freed once the sound player is no longer needed. This is done by calling ISOUNDPLAYER_SetInfo(? NULL);

l. Sound seems to be playing at a fixed volume. What API can I use to control the sound volume? Applicable Releases: 1.0, 1.1, 2.0 Use ISOUND_SetVolume() to control sound volume. To direct the sound towards an external speaker (if the handset has one), set AEESoundInfo.method to AEE_SOUND_METHOD_RING / AEE_SOUND_METHOD_BEEP for ringer / key beeps and AEESoundInfo.eDevice to AEE_SOUND_DEVICE_HANDSET using ISOUND_Set() and ISOUND_SetDevice().

m. Is it possible to play more than one tone simultaneously? Applicable Releases: 1.0, 1.1, 2.0

45

In BREW version 2.0, the IMEDIA interface can be used to play multiple QCP files (maximum 4) simultaneously on CMX 2.x based devices. In addition to this 1 MIDI file can also be played along with the 4 QCP files allowing a total of (4QCP + 1MIDI) 5 different files to play simultaneously. To do this create 4 IMedia objects for MIDIOutQCP by calling ISHELL_CreateInstance(?,AEECLSID_MEDIAMIDIOUTQCP). Initialize each of these objects with their respective data by calling IMEDIA_SetMediaData and play them using IMEDIA_Play().

Simultaneous tones and files cannot be played in BREW versions 1.0 and 1.1. If a call is made to play the second tone before the first tone is finished playing, the first tone will be aborted.

n. How do I load multiple sound files without exceeding the maximum number of files limitation? Applicable Releases: 1.0, 1.1, 2.0 One possible solution is to store multiple sound files as a single file. You can load the appropriate sound clip into a buffer and play from that buffer using ISOUNDPLAYER_SetStream.

For example://Open the file for reading and store to our apps file pointer.pMe->m_pIFile = IFILEMGR_OpenFile(pMe->m_pIFileMgr, pMe->MultipleMidiFile, _OFM_READ);

if (!pMe->m_pIFile)return FALSE;

// Calculate DESIRED_OFFSET (not shown)

if (IFILE_Seek(pMe->m_pIFile, _SEEK_START, DESIRED_OFFSET) != SUCCESS )return FALSE;

// The function asynchronously triggers a AEE_SOUNDPLAYER_STATUS callback.ISOUNDPLAYER_SetStream(pMe->m_pISoundPlayer, (IAStream *)pMe->m_pIFile);

o. Where do I store ringer files? Where does the IRINGERMGR_Create() function create my ringer? Applicable Releases: 1.0, 1.1, 2.0 The sound files to be used as ringers by the handset should be stored under the AEE_RINGER_DIR. This directory is OEM dependant and the appropriate path is stored in this constant by the OEM. The IRINGERMGR_Create function creates the file in the ringer directory as defined by the AEE_RINGER_DIR constant.

When creating a ringer, please make sure that your application has the appropriate

46

privilege levels:In Brew v 1.0: Please check the "Write Access to shared directory" checkbox.In Brew v 1.1 onwards: Please check the "Write Access to ringer directory" checkbox.

p. Can we set the ringer on the device using BREW APIs? Applicable Releases: 1.0, 1.1, 2.0 The IRINGERMGR_SetRinger API can be used to set the ringer. However, OEM support for this functionality is also required. Some OEMs do not support this feature and you need to use the native UI to set the ringer.

Memory Managementa. Please explain the memory architecture in BREW? Applicable Releases: 1.0, 1.1, 2.0 BREW device has Flash RAM and Heap RAM. You can treat Flash RAM as a hard drive. Programs are stored there, but not run from it. You can treat Heap RAM as you would always treat a memory heap. Say you have an application that is 35k in size. This will take 35k from the Flash RAM to store on the device. When the application is run, the 35k will be loaded into Heap RAM in its entirety plus however much Heap RAM it needs to allocate. When the applet is released, this Heap RAM is freed. It will still occupy space on the Flash RAM until it is removed from the device.

b. How has Memory Management changed in BREW 2.0? Applicable Releases: 2.0 In Brew 2.0 when an interface is released, and the reference count reaches 0, the memory is set to 0xfefefefe. In previous BREW versions, the memory was left in tact and assumed to be garbage, but if you did not set your pointer to NULL then you would still have a pointer to the memory.

c. How do I make sure that memory accesses are properly aligned? Applicable Releases: 1.0, 1.1, 2.0 When running on the ARM processor it's a good idea to make absolutely certain that all memory accesses are properly aligned. Accessing misaligned data as non-byte values will cause an exception unless the element is specifically identified as PACKED. This is normally caused by references to elements within byte arrays or streams as ints, etc.

Alignment problems can arise when you improperly cast a pointer to a byte-sized item to a pointer to larger item (for example, to a structure, short or long). Generally, it is best to avoid such casts altogether. MALLOC() is one case where pointers must be cast, but MALLOC returns pointers that are properly aligned for any size. If you have any customized allocators, keep this in mind.

Usually it's a good idea to arrange the fields of a struct such that 32-bit fields come first, followed by 16-bit fields and then any 8-bit fields. This helps for both padding and alignment if one writes the struct into a file.

47

d. What's the difference between MALLOC() and IHEAP_Malloc() functions in the BREW SDK? Applicable Releases: 1.0, 1.1, 2.0 MALLOC and IHEAP_Malloc() are identical, just as FREE and IHEAP_Free() are identical. In earlier versions of the BREW SDK, malloc was part of the IHEAP Interface, and was later made into a helper function for ease of use. Both are still available for backward compatibility, but it is recommended that you use MALLOC and FREE rather than IHEAP_Malloc() and IHEAP_Free().

An app needs to create IHeap interface only when it wants to get current memory usage statistics (IHEAP_GetMemStats()) or check if a memory block of a certain size can be allocated (IHEAP_CheckAvail()).

e. What is the size limit for a BREW application? Applicable Releases: 1.0, 1.1, 2.0 The size of a BREW applet is limited by the amount of free file system space that is available, and by the amount of available RAM.

BREW applets, when executed, are loaded into RAM; any RAM left over can be used for memory allocation, loading resources, creating controls, etc. How much RAM is available depends on the type of phone, and its configuration. On a QCP-3035, for instance, the available RAM is 90K, 30K of which belongs to BREW and other phone related tasks, leaving 60K available for use by an applet. The memory available on each of the phones running BREW is available here.

Another limiting factor for applet size is heap fragmentation. If the largest available memory block is smaller than the size of the applet, then the applet will not be loaded. Use IHEAP_CheckAvail() to determine whether a memory block of sufficient size can be allocated. IHEAP_GetMemStats() can be used to determine the amount of RAM already used. If you have an applet that is too large for a particular device, a work-around is to split the application into multiple applets. Memory Allocation provides more information on how to avoid heap fragmentation.

Notes: In order test a low memory condition on the BREW Emulator reduce the heap size in

the Device Configuration file by the appropriate amount. BREW's System Info screen reports the amount of available flash memory, not the

amount of available RAM.

f. Why can't an application be run directly from Flash RAM? Applicable Releases: 1.0, 1.1, 2.0 BREW loads the apps into Heap RAM because files on EFS are stored as non-contiguous blocks.

48

MIF Settings

Extensionsa. What guidelines should I follow when creating extensions? Applicable Releases: 1.0, 1.1, 2.0 Please make sure that you are following the guidelines below in your applet class's MIF file and in the extension class's MIF file.

1. In the Extension class's MIF file: The Extension's Class ID should be listed in the Extensions tab under Exported classes. It should not be listed on the Applet tab under Applet Information. If listed under Applet Information, BREW™ will think that the Class ID belongs to an applet. Only the system can use ISHELL_CreateInstance() to create an instance of an applet. 2. In the Applet class's MIF file: List the Applet Class ID under Applet Information. Select the necessary privilege levels (General tab). List the extension class(es) in the Dependencies tab. Please note that a single MIF file cannot contain both an applet and a class ID (with same or different Class IDs).

There is a bug in the Extensions and ExtUse example shipped with the 1.0 SDK. Please refer to "Bug in ExtUse and Extensions example KI" for more information.

b. When I remove all apps dependent on a certain module using Mobile Shop, I sometimes notice that the common module is not removed. Why? Applicable Releases: 1.0, 1.1, 2.0 There is a bug in Mobile Shop that causes this behavior if the apps are removed consecutively, without exiting Mobile Shop in between app removals.

For example, say you have two apps loaded that have dependency on a common module. If you remove the two apps using Mobile Shop in succession (without exiting Mobile Shop in between removals), you will see that the common module still remains. If, however, you exit and restart Mobile Shop between removals, the common module is also removed, which is the expected behavior.

c. My extension needs to call APIs that require privilege settings. Should I set the privilege levels in my extension? Applicable Releases: 1.0, 1.1, 2.0 BREW Extensions execute in the context of the calling application and hence inherit all properties of the calling application, such as: Privilege Levels, Directory Permissions, etc. It is useless to specify additional privilege levels in the extension. To ensure that all applications using your public extension set the required privilege level, you should note this in your extension documentation.

49

d. My extension needs access to resource and data files. How do I include resource and data files into my extension package? Applicable Releases: 1.0, 1.1, 2.0 An extension runs in the context of the calling application. An extension can therefore create / access files only from the application's directory and from the shared directory.

In our current design, an extension can access bar files if they are in the *application's* directory. We will be fixing this in an upcoming BREW release, so that extensions can access bar files from the extension's directory.

Extensions can access data files from either the shared directory or the calling application's directory. The extension cannot see the data file in its directory and neither can the calling application, therefore if your extension requires access to a data file, the data file will need to be downloaded into the shared directory during run-time. We are working to allow extensions to access data and bar files in the extension directory in an upcoming BREW SDK™ release/patch.

e. Why do files created by my extension appear in the calling application's directory? Applicable Releases: 1.0, 1.1, 2.0 Files created by an extension are created on behalf of the calling application, and hence they are created in the application directory. The reason for this is that numerous applications may be calling the extension, and if created in the extension directory would be accessible to all apps calling the extension.

f. What is the difference between protected and unprotected extensions? Applicable Releases: 1.0, 1.1, 2.0 A protected extension can only be used by applications that have an explicit dependency on the extension (set in the Dependency tab of MIF file). Unprotected extensions can be used by any application, irrespective of whether the application declares a dependency on it. Unprotected extensions may export a MIME type, so that an application can make use of its services. For more information on exporting MIME Types, please refer to the MIF Editor Guide.

An app can use an extension that is has declared dependency on it, as well as any unprotected extensions. So if app A declared a dependency on unprotected extn B, then app C could utilize extn B if it became aware of it. However, if extn B was protected, app C could not use it unless it depended on extn B.

Some features that unprotected vs. protected extensions can be used for are1. Enforcing which apps are 'privileged' to use the extension2. Pre-packaged extensions that can be used by all apps on the phone.

g. Why does ISHELL_CreateInstance() return EPRIVLEVEL when trying to create an instance of an extension class? Applicable Releases: 1.0, 1.1, 2.0

50

EPRIVLEVEL error indicates that you do not have the proper dependencies in your MIF file. If an application wishes to use a protected extension, it must declare dependency on the extension in the application's MIF file. Please refer to What is the difference between protected and unprotected extensions? for information on the differences between protected and unprotected extension.

h. Can an application be both an applet and an extension? Applicable Releases: 1.0, 1.1, 2.0 This is not possible. An application can be either an extension or an applet. Please refer to What guidelines should I follow when creating extensions? for information on how to architect your application and extension.

i. Can an extension depend on an applet? Applicable Releases: 1.0, 1.1, 2.0 No, this is not currently possible. We are working to allow this in a future release.

j. Can an extension depend on another extension? Applicable Releases: 1.0, 1.1, 2.0 No, this is currently not supported.

k. When an application using an extension is launched, is memory allocated for the application as well as any extensions it calls? Applicable Releases: 1.0, 1.1, 2.0 BREW allocates memory only for the loaded applet. When a call is made to another module/extension, the module is loaded. When the application creates an instance of an extension, that extension and any memory it allocates are marked for the app. Hence, when the app is released, it should free the extension (and the extension must in-turn free all the memory it allocated).

The module is marked as an idle module when BREW no longer holds reference to it. Idle modules are released when 1. The system is running low on memory OR2. The app closes

l. When are extensions deleted? Do they need to be deleted explicitly or are they deleted when the using application is removed? Applicable Releases: 1.0, 1.1, 2.0 Extensions are either:3. Downloaded with applications that declare dependency on them.4. Already exist on the phone because another application downloaded it5. Prepackaged on the phone (come with the phone).In an application is deleted, any extensions it depends on are also deleted unless there is another application that declares dependency on those extensions. Pre-packaged extensions are not deleted with the application.

51

m. l. After releasing an extension, I find that the memory obtained by IHEAP_GetMemStats does not go down by the size of the extension. Why? Applicable Releases: 1.0, 1.1, 2.0 BREW holds a reference to the extension's Module even after the extension is released. This is why the memory used does not go down by the full size of the extension module when the extension is released.

BREW will clean up the idle modules (modules with reference count of 1 - the single reference being the one that BREW holds) when6. The app exits OR7. The system is running low on memory.

n. I am interested in using a public extension. Where can I find the extension and how do I incorporate it into my application? Applicable Releases: 1.0, 1.1, 2.0 Information on available public extensions can be found on the Developer Extranet under Business Operations->Application Extensions. This information includes the supported platforms, the pricing plan, documentation and a usage example.

Licensea. Which versions of BREW support ILicense?

Applicable Releases: 1.0, 1.1, 2.0 All versions of BREW support ILicense. It isn't however documented in the BREW 1.0 API Documentation.

b. What does each of the Price Types mean? Applicable Releases: 1.0, 1.1, 2.0 PT_DEMO - Demo versionThis version is the demo version and is a free trial of the application. The demo version may have one of the following license types: 1) Number of Uses = 1 to 10 uses2) Elapsed Time = 1 to 10 minutes3) Number of Days = 1 day

PT_PURCHASE - Purchase versionMay be purchased for a specific number of uses (LT_USES), number of days (LT_DAYS), until a certain date (LT_DATE) or for a specific number of minutes (LT_MINUTES_OF_USE).

PT_SUBSCRIPTION - Subscription version.This version of the application is associated with a monthly fee.

52

PT_UPGRADE - Upgrade.This version of the application is to upgrade the current version of the application already present on the handset.

Please refer to https://brewx.qualcomm.com/developer/extranet/operations/brewpricingoptions.pdf (Developer Extranet access required) for more information on Pricing Plan Options.

c. What does each License Type mean? Applicable Releases: 1.0, 1.1, 2.0 LT_USES: The license expires after a certain number of uses as defined by the application. Its value is the number of uses remaining. LT_DATE: The license expires on specified date. Its value is date/ time of expiration.LT_DAYS: The license expires a number of days after downloading. Its value is the time of expiration.LT_MINUTES_OF_USE: The license expires after application has been active a certain number of minutes. Its value is the number of minutes remaining.

d. d. How can I selectively expose or hide features of my application based on whether the license type is DEMO or non-DEMO? Applicable Releases: 1.0, 1.1, 2.0 In BREW 1.1 onwards, you can control what parts of your app will not be available to a demo license app by checking the pricing type using ILICENSE_GetPurchaseInfo().

e. What aspect of licensing does the application have to handle and what will BREW handle? Applicable Releases: 1.0, 1.1, 2.0 BREW handles the license decrementing for following license types: LT_DAYS, LT_DATE and LT_MINUTES_OF_USE. BREW does not handle license management for usage-based license (LT_USES).

BREW does not define what a single use of the application is and hence cannot know when to decrement the usage count. The application must define what a single use is and after each use, the application must decrement the usage count using the ILICENSE_DecrementUsesRemaining() API.

In BREW 1.0, when the number of uses remaining is zero, the user will not be allowed to launch the app. In 1.1 onwards, the user will be able to launch the zero-license app, and the app must handle the zero-license condition.

f. How do I add License information to my application? Applicable Releases: 1.0, 1.1, 2.0 You can add usage-based License information for test purposes using the 2.0 MIF Editor.

53

The 2.0 MIF Editor can read 1.0, 1.1 and 2.0 MIF files and save the files in the respective formats (use File->Save As and choose appropriate Type - 1.0/ 1.1/ 2.0).

**IMPORTANT: When submitting your app for TRUE BREW® Testing, the MIF file should not contain any license info. Even if your app is purchase license based, the MIF file you submit must not contain any license info. After your app passes TRUE BREW Testing, you will be able to set purchase info through the Developer Extranet

g. My application has X number of minutes remaining, but I can run it for more than X minutes. Why? Applicable Releases: 1.0, 1.1, 2.0 BREW does not check for the license validity while the app is in execution. BREW checks for valid license only when the application is launched.

If the application has exceeded its expiration time in a LT_DATE, LT_DAYS, or LT_MINUTES_OF_USE license type, then BREW will prevent the application from launching. The user can launch the app if he has "X" minutes of use and can use that app for any number of minutes [N] ( N > = X ) . If he exits the app after "X" minutes, the app will fail to launch again. The application can, of course, monitor its own activity time while it is running, and handle such expirations as it wishes.

If using minutes of use as a monetization scheme and the end user never quits the app, the end user can use the app for as long as they like. Developers should therefore monitor the time in use in their own app if they want to ensure that end users cannot use their app beyond a certain time.

h. When running an app with Usage-based license, why does the number of uses remaining get reset to the original value when the phone is power cycled? Applicable Releases: 1.0 Please refer to Number of Uses License is reset when phone is power-cycled Known Issues.

i. Will the applications license information be erased when the application is disabled? Applicable Releases: 1.0, 1.1, 2.0 When an application is disabled, the application's MIF file remains on the device. The MIF file contains the license information and hence, disabling the application will not affect the license information.

j. What happens when a Demo expires? Can I download a demo again after it expires? Applicable Releases: 1.0, 1.1, 2.0 When a Demo expires, the user has two options:1. Delete the application: Upon doing so the application directory is removed with all its

54

contents, including any data files, subdirectories, etc. that may have been created after the application was first downloaded to the phone.2. Continue with the application: Upon doing so they must they must go through the steps of purchasing time; all settings, data files, etc. are preserved.

Mobile Shop keeps track of demos that the user has tried, and will prevent them from trying to "cheat" by deleting, then re-downloading an application demo.

k. Why does the MIF Editor allow only the addition of Usage based license information? Applicable Releases: 1.0, 1.1, 2.0 Since BREW handles all license types other than LT_USES, the ability to set and test other license types have been excluded from the MIF Editor and License Editor. Please refer to "What aspect of licensing does the application have to handle and what will BREW handle?" for information on Usage based license type.

MIF Imagesa. What images do I need to include in my application and what are their size requirements? Applicable Releases: 1.0, 1.1, 2.0 All BREW applications are required to include the following three application images with the specified pixel dimensions:

Thumbnail: 16 x16 PixelsIcon: 26 x26 PixelsImage: Maximum size is device specific

The Image size are as follows:

QCP3035: 69 x 46 Pixels, or smaller

Sharp Z800: 108 x72 Pixels, or smaller

LG VX-10: 120 x100 pixels, or smaller

Motorola T-720: 120 x 93 pixels or smaller

Toshiba/Audivox CDM-9500: 100 x 100 pixels or smaller

LG VX-4400: 100 x 100 pixels or smaller

Samsung A-530: 26 x 26 pixels or smaller

KWC 3225: 65 x 42 pixels or smaller

On BREW 2.0 devices, the Image should be 65x42 pixels, or smaller.

55

The images must have transparent background. For information on image transparency, please refer to What is the transparent color on color and monochrome phones?.

These images are used by the App Manager. In devices that use a soft key menu, the Thumbnail is used in the soft key menu and the Image is used in the center. In devices that use the icon menu, only the Icon is used. BREW applications are required to contain all 3 images, irrespective of the display method used by the target device.

b. Why does the generic BREW icon/thumbnail/image show in BREW Application Manager instead of the images contained in my MIF file? Applicable Releases: 1.0, 1.1 There is a bug in the 1.x MIF Editor that requires the full image path to be present when the MIF file is saved. Please refer to Generic BREW icon/thumbnail/image is saved in MIF file if full image path is not specified when MIF file is saved.

Privilegesa. Tell me more about the BREW privilege levels. Applicable Releases: 1.0, 1.1, 2.0 Privilege levels provide an additional level of security by controlling access to API classes. An applet must have the appropriate privilege level in order to use certain classes. The extensions that an applet depends on inherit the privilege levels from the calling application. There is no need to specify additional privilege levels in the extension.

Privilege levels for an applet are specified in its corresponding MIF, which you create and maintain via the MIF Editor.

For example:In order to use the IFile, IFileMgr, IDatabase, IDBMgr, IDBRecord, ISound and/or ISoundplayer API classes, an applet must have the File privilege level.

In order to use the INetMgr and/or ISocket ISoundplayer API classes, an applet must have the Network privilege level.

In order to create an instance of a protected extension, the application must declare dependency on the extension. For more information on protected vs non-protected extensions, please refer to What is the difference between protected and unprotected extensions?

If the appropriate privilege level is not selected, the ISHELL_CreateInstance() for that class will not succeed.

Two other privilege levels, namely Download and All, show up in the "Advance Privilege Levels" dialog box in the MIF. These are intended for use by carriers or device manufacturers

56

only. If you are an applications developer, selecting these Privilege Levels will cause your application to fail TRUE BREW testing.

b. Why do I get EPRIVLEVEL 21 error on ISHELL_CreateInstance() call? instead of the images contained in my MIF file? Applicable Releases: 1.0, 1.1 This is an indication that you do not have the necessary permission to create the specific class. Make sure that the necessary privileges are checked in the app's MIF file (General Tab). Please refer to Tell me more about the BREW privileges.

If you are calling a non-applet class (class_a) from within an applet (class_b), you need to do the following in order to have the necessary privileges:

1. In class_b's mif file, specify class_a's external class ID (Dependencies tab in MIF Editor). 2. In class_a's mif file, you need to export its Class ID (Extensions tab in MIF Editor).

Another possible reason for the EPRIVLEVEL 21 error is if the application uses a Class ID that is reserved by BREW. Class IDs less than 0x02000000 are reserved by BREW. Therefore, when generating a class IDs locally using the MIF Editor, you should use class IDs larger than 0x02000000.

c. Where can I find the definitions of the various privilege levels (wPrivWant) for the ISHELL_CheckPrivLevel() API? instead of the images contained in my MIF file? Applicable Releases: 1.0, 1.1 The privilege levels are described in the API reference document under AEE Privilege Levels. The definitions of these privilege levels are missing in SDK Version 1.1. This is a bug in SDK Version 1.1. Please create a header file with the following definitions and include the header file in your project:

#define PL_FILE (0x0001) // IFileMgr, IDBMgr

#define PL_NETWORK (0x0002) // INetMgr

#define PL_TAPI (0x0004) // ITAPI Access

#define PL_SHARED_WRITE (0x0040) // Write Access - Shared Directory

#define PL_POS_LOCATION (0x0080) // Position location access (ISHELL_GetLocation)

#define PL_RINGER_WRITE (0x0100) // Write Access - Ringer Directory

#define PL_ADDRBOOK (0x0200) // Access to Address Book

#define PL_SECTORINFO (0x0400) // GetSectorInfo

#define PL_SYSTEM (0xffff)  

57

In Version 2.0, the privilege level definitions are included in AEE.h.

Screensavera. How do I develop BREW screensaver applications? Applicable Releases: 2.0 Screensaver applications can be developed only with the BREW 2.0 SDK. A screensaver application similar to other BREW applications, with the following exceptions:

The SCREEN_SAVER flag should be set in the MIF (Applet Tab->Advanced). Also, if you do not want the screensaver application to show as a regular application in the Application Manager, set the applet type in the MIF to HIDDEN (Applet Tab->Applet Type).

The application should handle the EVT_APP_CONFIG event. This allows the screensaver application to perform any necessary configuration. To do this, you should a. Set "Show on Config Menu" flag in the MIF Editor (Applet tab->Advanced)b. Your app should handle EVT_APP_CONFIG event

In order to test your screensaver application, you should add MIME type and Base Class information to your MIF file. Please note that you must remove these changes before submitting the application for TRUE BREW® Testing:

Include MIME type and Base Class information. This is done for as follows:a. In the MIF editor, click on the Extensions tab.b. Under Exported MIME types, click New... and you will get a dialog boxc. Enter MIME type: brew/ssaver Base Class: 0x01010101 (i.e. AEECLSID_SCREEN_SAVER = AEECLSID + 1) Handler Class: your screensaver application's class id

On commercial devices, the above-mentioned MIME registration for the Screensaver must be removed. The BREW Application Manager on the device will provide an option for the user to select the desired Screen Saver. Once the application is selected to be the screen saver, it will be launched automatically by BREW when the device has received no keypad activity for a fixed period of time. This time period can be configured by the app (please refer to How do I change the timeout value for the screensaver? for information on how to configure the timeout value ) but the OEMs have minimum and maximum limit within which this value must exist. The screen saver is dismissed and the currently loaded application resumes when the user presses any key.

b. Is it possible to prevent the screensaver application from running while my application is inactive? instead of the images contained in my MIF file? Applicable Releases: 2.0 Yes, it is possible to prevent your application from being interrupted by the screensaver application when the screensaver's timeout value has elapsed. To make this work, the non-

58

screen saver application (Hello World, for example) must return TRUE to the EVT_BUSY event. This will prevent the screen saver application from running as long as Hello World is running.

c. Does the Brew screensaver get activated when the native UI is inactive? Applicable Releases: 2.0 Yes, after the screensaver timeout value has elapsed.

d. How do I change the timeout value for the screensaver? Applicable Releases: 2.0 The following code snippet sets the timeout value for your screen saver.

AEEScreenSaverInfo si;si.wSecs = ISHELL_SetPrefs(pShell, AEECLSID_SCREEN_SAVER, SSINFO_VER, &si, sizeof(si));

// SSINFO_VER is found in the AEEShell.h file and it is the version of the preference resource.

The ideal place for this code snippet is in your application's EVT_APP_CONFIG event handler.

Othera. Can my BREW application access resources and strings set in my application's MIF file? Applicable Releases: 1.0, 1.1, 2.0 You can access strings in your application's MIF file via the following APIs: ISHELL_GetAppAuthor(), ISHELL_GetAppCopyright(), ISHELL_GetAppVersion(), ISHELL_ShowCopyright(). These APIs are available in the BREW 2.0 SDK onwards.

In all SDK versions, it is possible to use the MIF file as a normal resource file. When developing/submitting an application one does not know what the name of the MIF file will be when the application is downloaded onto the handset. To get the name of the MIF file the following snippet of code can be used.

AEEAppInfo ai;

// Get the app info, which contains the name of the MIF fileif (ISHELL_QueryClass(pMe->a.m_pIShell, AEECLSID_MYAPP, &ai)) {char * szMIFName;

// ai.pszMIFcontains the name of the MIF file.szMIFName = ai.pszMIF;}

59

To load the resources from the MIF File the ISHELL_LoadResString() and ISHELL_LoadResImage() functions can be used. BREW will first look for the resource file in the application directory. If not found, BREW will look in the /brew directory and if still not found, BREW will look in the language specific directory. The resource IDs to be passed to these functions are defined in AEEShell.h as follows.

//Absolute IDs#define IDS_MIF_COMPANY (6) // Company Name#define IDS_MIF_COPYRIGHT (7) // Copyright Date#define IDS_MIF_VERSION (8) // Module version

typedef struct{

AEECLSID cls;  

char * pszMIF; // App Resource file

uint16 wIDBase; // Base ID for locating title, icon, etc

uint16 wAppType; // Extended OEM/Carrier App Type

uint16 wPad2;  

uint16 wPad3;  

uint16 wPad4;  

uint16 wFlags; // Applet Flags (AFLAG_...)

} AEEAppInfo;

// Standard Applet Resource Offsets - These offsets begin at

AEEAppInfo.wIDBase.  

#define IDR_NAME_OFFSET 0

#define IDR_ICON_OFFSET 1

#define IDR_IMAGE_OFFSET 2

#define IDR_THUMB_OFFSET 3

#define IDR_SETTINGS_OFFSET 4

#define IDR_VERSION_OFFSET 5

60

#define IDR_OFFSET_STEP 20

For example, To load the company name call:ISHELL_LoadResString(pMe->a.m_pIShell, ai.pszMIF, IDS_MIF_COMPANY, Company, sizeof(Company));

To load the thumbnail image call:ISHELL_LoadResImage(pMe->a.m_pIShell, ai.pszMIF, AEEAppInfo.wIDBase + IDR_THUMB_OFFSET, ThumbnailImage, sizeof(ThumbnailImage));

Miscellaneousa. How do I get a BREW-enabled phone? Applicable Releases: 1.0, 1.1, 2.0 If the phone is available in your marketplace you can simply purchase the phone off the shelf. We are currently working on preparing regional phone labs to provide developers a place to test and develop applications on prototype phones or phones available in various markets throughout the world. We are also discussing the need to offer developers additional solutions with the phone manufacturers.

b. Can the ESN or other unique identifier be obtained using the BREW API? Applicable Releases: 1.0, 1.1, 2.0 There is currently no BREW API to obtain the device's ESN. A unique device identifier that can be accessed via BREW API is the device phone number. Please refer to How do I obtain the phone number of the device on which my application is running?.

c. How can I determine the phone model on which my application is running? Applicable Releases: 1.0, 1.1, 2.0 There is no API to determine the phone model. In BREW SDK 2.0 onwards, you can get the Platform ID on which your application is running by calling ISHELL_GetDeviceInfo(). In order to access the Platform ID with this call, the AEEDeviceInfo.wStructSize field must be filled prior to this call.

d. Where should I send my phone when it needs to be re-flashed, or have DNS configured or test-bit enabled? Applicable Releases: 1.0, 1.1, 2.0 You can send the phone via a fully trackable carrier such as Federal Express (not U.S. Postal Service) to:

QUALCOMM, Inc.Attn: QIS Phone Center (Bldg. Bldg R - 212P)5775 Morehouse Dr.San Diego, CA 92121

61

Please include a note with the following information:1. Return address and phone number2. Phone issue/Nature of request: Reflash, Configure DNS, Phone error, etc.3. ESN Number4. If activated, with which phone number and carrier5. Is the phone's browser activated?

e. How do I determine the software version of my phone? Applicable Releases: 1.0, 1.1, 2.0 On the Kyocera 3035:

Navigate to the idle screen Key in 111111, then press Select key Select 'Version' menu item Look for the version number specified under SW Version. For example: LR2.0.31

On the Sharp Z-800: Main Menu-> Display-> Version.

On the LG VX-10: Main Menu-> Display-> Version.

On the Motorola T-720: Navigate to Main Menu (by pressing top, center button) Software Version can be found under Settings-> Phone Status->Other Information->

S/W Version.

On the Toshiba/Audiovox CDM-9500: Main Menu-> Display-> Information->Version.

On the LG VX-4400: Menu ->Information (9) -> S/W Version

On the Samsung A-530: Menu-> Setup ->Version

On the Samsung A-561: Menu-> Setup ->Version

On the Kyocera 3225: Menu-> Phone Info-> SW Version

f. How are random numbers generated in BREW? Applicable Releases: 1.0, 1.1, 2.0

62

GET_RAND() uses the current CDMA time as the random number seed. This ensures that a unique sequence of random numbers is generated each time GET_RAND() is called.

g. Does BREW have support for e-mail? Applicable Releases: 1.0, 1.1, 2.0 There is currently no native support for email protocols in the BREW API.

h. Does BREW natively support text-to-speech or speech-to-text? Applicable Releases: 1.0, 1.1, 2.0 No, but third-party companies can develop this functionality and expose an interface for other applications to take advantage of the feature.

i. Does BREW support Bluetooth? Applicable Releases: 1.0, 1.1, 2.0 Yes, BREW supports Bluetooth in BREW SDK 2.0 onwards. Please note that OEM support for this feature is required.

For more information on Bluetooth APIs, please refer to IBTAG, IBTSDP, IBTSIOPORT APIs in the BREW API Reference Guide.

j. Under what circumstances will an applet fail to start? (i.e., ISHELL_CanStartApplet() returns FALSE) Applicable Releases: 1.0, 1.1, 2.0 An applet will fail to start in cases where a critical dialog, such as Privacy Alert dialog, is being displayed. Some cases are OEM dependent, such as whether an applet will start when there is an ongoing voice or data call. The Kyocera 3035, for example, allows an applet to be started when a voice call is in progress, whereas the Sharp Z-800 does not.

k. Is it possible to implement VOIP protocols on BREW? Applicable Releases: 1.0, 1.1, 2.0 Yes, it is possible to implement VOIP protocols on BREW. However, we do not have any documentation describing this nor any VOIP-specific APIs.

Networking and TAPI

Network Programminga. When will BREW offer HTTP Support? Applicable Releases: 1.0, 1.1, 2.0 HTTP Support is available through the AEEWeb interface in version 1.1 of the BREW SDK™ and above. With earlier versions of the SDK, use the ISocket interface to connect to a server's HTTP port, and send HTTP "get" and "post" requests.

Please refer to the RoadWarrior sample application that ships with the BREW SDK for an example of using ISocket to communicate with an HTTP server.

63

b. Why does GetHostByName() not work on my phone? Applicable Releases: 1.0, 1.1, 2.0 For INETMGR_GetHostByName() to function correctly, the phone's Domain Name Server (DNS) settings must be properly configured. This is generally taken care of by the Service Provider, in which case the phone should be returned to the place of purchase, or an authorized service center so that its DNS settings can be properly configured.

For the time being, North American customers may send their phones to QUALCOMM for DNS configuration. This is an interim solution that will be used until Service Providers are set up to handle the DNS configuration of customer phones. Please refer to this FAQ for information on where to send your phone to get DNS configured.

c. Why do I get the value of 0.0.0.0 in dnsresult.addrs when I use GetHostByName()? Applicable Releases: 1.0, 1.1, 2.0 This may be due to incorrect implementation of error handling in the GetHostByName() callback function. The error handling implementation in the GetHostByName() callback of the NetSocket example is incorrect. Please use the following sample implementation:

if(pMe->dnsresult.nResult > 0 && pMe->dnsresult.nResult <= AEEDNSMAXADDRS) { // DNS lookup success // Process dnsresult.addrs for(i = 0; i < pMe->dnsresult.nResult; i++) { SPRINTF(szMsg,"Addr=: %x",pMe->dnsresult.addrs[i]); DisplayOutput(pMe,i+4,szMsg); } } else { // DNS Failure - error code is dnsresult.nResult SPRINTF(szMsg, "DNS: error %d", pMe->dnsresult.nResult); DisplayOutput(pMe, 2, szMsg); }

d. With no TCP/IP Flush command available in BREW, how can I confirm that a command is sent right away? Applicable Releases: 1.0, 1.1, 2.0 It is not possible to determine when a TCP/IP command is sent; BREW does not provide this capability.

e. What is the largest packet size supported by BREW? Applicable Releases: 1.0, 1.1, 2.0 The maximum packet size is OEM dependant, and may vary from one manufacturer's phone to another. BREW has no control over this limitation.

f. When transmitting large files, do I have to break the file up into packets before sending, or does BREW do this for me? Applicable Releases: 1.0, 1.1, 2.0 You should simply send what you can, and ISOCKET_Write() will tell you how much data was actually sent. If there is data remaining to be sent, simply offset your data pointer by the amount indicated by your last call to ISOCKET_Write().

64

For example:

void CommonWriteCB (void *pUser) {char *psz = NULL;int cbWrite;???br>SampleApp * pMe = (SampleApp*)pUser;

// pszData is the data to be writtenpsz = pszData;cbWrite = STRLEN (pszData);

// Loop till all the bytes are written.while (cbWrite > 0) {rv = ISOCKET_Write(pMe->m_pISocket, (byte *)psz, (uint16)cbWrite);

if (rv == AEE_NET_WOULDBLOCK) {// No byte were written successfully. Register // callback to try again later.ISOCKET_Writeable(pMe->m_pISocket, CommonWriteCB, (void *)pMe);return;} else if (rv == AEE_NET_ERROR) {// Write Error.ReleaseNetAndSocket(pMe);return;}

// In case of parital write, loop and write the rest cbWrite -= rv;psz += rv;}???br> }

g. How many sockets can be opened simultaneously? Applicable Releases: 1.0, 1.1, 2.0 This limit is OEM specific, and will vary depending on the device that your applet is running on---it is not set by BREW.

Please note that multiple TCP sockets are not supported on the Kyocera 3035. It allows one TCP socket and one UDP socket at a given time.

65

h. Are network callbacks invoked in the context of the main thread, and if so how is the data integrity preserved in the current context? Applicable Releases: 1.0, 1.1, 2.0 All network callbacks occur within the same thread context, at some point in time after the caller returns control to the AEE event loop. If your application is busy doing something, callbacks will be queued, then invoked once your application returns control to the AEE event loop, ensuring data integrity.

i. When reading from a socket the phone reads whatever it can in one go, while the emulator reads large packets in chunks. Why? Applicable Releases: 1.0, 1.1, 2.0 This is a limitation of the phone.

Your program should call ISOCKET_Readable() to be informed when more data can be read from the stream. The callback routine registered by ISOCKET_Readable() will be invoked whenever data becomes available---you can usually call ISOCKET_Read() at this point. Continue calling ISOCKET_Readable() for as long as your program expects more data.

rv = ISOCKET_Read(piSock, (byte *)szBuf, sizeof(szBuf));

if (rv == AEE_NET_WOULDBLOCK) {// WOULDBLOCK => no more data available at the moment// Register the callback to read the data later.ISOCKET_Readable(piSock, CommonReadCB, (void*)pMe); return;} else if (rv == AEE_NET_ERROR) {// error reading from socketReleaseNetAndSocket (pMe);}else if (rv > 0) { // rv bytes of data has been read from the socket into // szBuf

// Read remaining dataISOCKET_Readable(piSock, CommonReadCB, (void*)pMe); }else { // rv == 0 // There is no more data to be received. // The peer has shut down the connection.ReleaseNetAndSocket (pMe);}

66

j. How can I check the status of my sockets and PPP connection? Applicable Releases: 1.0, 1.1, 2.0 You can check on the status of the PPP connection (active, inactive, opening or closing) using INETMGR_NetStatus().

NetState netState = NET_INVALID_STATE;AEENetStats netStats;netState = INETMGR_NetStatus (pINetMgr, &netStats);

You can use INETMGR_OnEvent() to monitor both the status of the PPP connection and socket connections. Refer to NetMgrEvent enum in AEENet.h for a list of all network and socket events.

// Register to receive Network and Socket eventsINETMGR_OnEvent(piNet, (PFNNETMGREVENT)CheckNetStatus, (void*)pMe, TRUE);

//Callback invoked when Network/Socket event is receivedstatic void CheckNetStatus(void* cxt, NetMgrEvent evt, uint32 dwData) {SampleApp *pMe = (SampleApp*)cxt;

if(evt == NE_PPP) { // network event. dwData = NetState enum value// refer NetState data structure in BREW API Reference doc}if(evt == NE_SO_CLOSING || evt == NE_SO_CLOSED) {// socket event - closing or closed. // DwData is pointer to socket}??br>return;}

k. Is it possible to transfer data between two phones? Applicable Releases: 1.0, 1.1, 2.0 Peer to peer connections between two phones have been found to be unreliable, failing when the phones are on the same subnet. It is best therefore to use a proxy server, transferring data between the phones using the server as a go between.

67

l. Can a BREW-enabled device be used as a server? Applicable Releases: 1.0, 1.1, 2.0 In addition to the obvious memory and performance limitations, it is not possible to listen on a socket connection when a BREW application is running on a phone. These factors make implementing a server on BREW difficult at best.

m. Is there any way to tell if a socket is already connected? Applicable Releases: 1.0, 1.1, 2.0 There are two ways to determine if a socket is connected. The easiest is to check the return value of ISOCKET_Connect(). When a socket is already connected, ISOCKET_Connect() will return EISCONN.

It is also possible to monitor the state of a socket connection by registering for the socket status change events NE_SO_CLOSING, and NE_SO_CLOSED with INETMGR_OnEvent(). Using this method, your application can avoid trying to connect an already connected socket.

To learn more about network and socket events, including NE_SO_CLOSING and NE_SO_CLOSED, please refer to the following include file: AEENet.h.

For example:

// Register to receive Network and Socket eventsINETMGR_OnEvent(piNet, (PFNNETMGREVENT)CheckNetStatus, (void*)pMe, TRUE);

//Callback invoked when Network/Socket event is received static void CheckNetStatus(void* cxt, NetMgrEvent evt, uint32 dwData){SampleApp *pMe = (SampleApp*)cxt;

if(evt == NE_SO_CLOSING || evt == NE_SO_CLOSED) {// flag set to false to indicate socket is disconnectedpMe->m_SocketConnected = FALSE;ReleaseNetAndSocket(pMe);}if(evt == NE_SO_CONNECTED) {// flag set to true to indicate socket is connectedpMe->m_SocketConnected = TRUE;}return;}

68

n. Why does ISOCKET_Release() return one when I am expecting a return value of zero? Applicable Releases: 1.0, 1.1, 2.0 When an application calls ISOCKET_Release(), the internal state of the ISocket object changes to "closing," and BREW begins waiting for the asynchronous "closed" event. Since the closed event is received in a callback, the reference count of the ISocket object is incremented to prevent it from being released before its internal state changes to closed.

o. Why does ISHELL_CreateInstance return ECLASSNOTSUPPORT when I try and create an instance of the net manager (AEECLSID_Net)? Applicable Releases: 1.0, 1.1, 2.0 This is probably because of the permissions on the MIF file for your applet. Please open your MIF file in the MIF editor and check the checkbox for Network privileges, then save.

p. Can I have a listening TCP socket? Applicable Releases: 1.0, 1.1, 2.0 No. We recommend you use UDP, specifically, ISOCKET_Bind and ISOCKET_RecvFrom.

q. Does BREW support blocking sockets? Applicable Releases: 1.0, 1.1, 2.0 No. BREW uses asynchronous sockets. You can use ISOCKET_Readable or ISOCKET_Writeable to be notified when it is safe to read/write.

r. How do I handle the case when I lose cellular coverage? Applicable Releases: 1.0, 1.1, 2.0 When the phone goes out of a coverage area, the data call will drop. When this happens, BREW cleans up the underlying OEM sockets that are in use. The ISocket(s) used by an app continue to exist, and the app will get appropriate error responses when it tries to use them.

For synchronous (TCP/IP) data communication, there are two ways to handle the potentially bad sockets:

1. Check the return value from all Socket operations

Writing or reading from the socket will cause AEE_NET_ERROR to be returned. In your code, you should check the return value from the Socket connect, read, write and take appropriate action.

In the code snippet below, appropriate action is to show the main menu:

// Connect callbackstatic void SampleApp_ConnectCB(void *cxt, int err) {SampleApp *pMe = (SampleAppApp*)cxt;

69

if (err) {// connect failedSampleApp_CleanUp(pMe);//Clean up net manager and // sockets ShowMainMenu(pMe);return;}

????br> }

// WritingiRet = ISOCKET_Write(pMe->m_piSock, (byte*)Request, (uint16)STRLEN(Request));if (iRet == AEE_NET_ERROR) {// Write errorSampleApp_CleanUp(pMe);// Clean up net manager and socketsShowMainMenu(pMe);return;}

// ReadingiRet = ISOCKET_Read(pMe->m_piSock, (byte*)buf, sizeof(buf));if (iRet == AEE_NET_ERROR) {// Read errorSampleApp_CleanUp(pMe);// Clean up net manager and socketsShowMainMenu(pMe);return;}

2. Register for change in network/socket state

Another way to handle the phone going out of coverage while a data call is in progress is to register for Network and Socket events using INETMGR_OnEvent() and take appropriate action when notified of change in network/socket status. In the example below, a flag is set to indicate that the socket is bad. The socket state is checked before it is used.

For more information on Network and Socket events, please refer to NetMgrEvent and NetState enums in aeenet.h include file.

70

For example:

// Register to receive Network and Socket eventsINETMGR_OnEvent(piNet, (PFNNETMGREVENT)CheckNetStatus, (void*)pMe, TRUE);

//Callback invoked when Network/Socket event is receivedstatic void CheckNetStatus(void* cxt, NetMgrEvent evt, uint32, dwData) {SampleApp *pMe = (SampleApp*)cxt;

if(evt == NE_PPP) {if(dwData == NET_PPP_CLOSING || dwData == NET_PPP_CLOSED) {// flag set to false to indicate socket is badpMe->m_SocketState = FALSE;

// clean up network and socketReleaseNetAndSocket(pMe);}}

if(evt == NE_SO_CLOSING || evt == NE_SO_CLOSED) {pMe->m_SocketState = FALSE;ReleaseNetAndSocket(pMe);}

if(evt == NE_SO_CONNECTED) {pMe->m_SocketState = TRUE;}

return;}

// Check socket state before using itstatic void RoadWarriorApp_ReadCB(void *cxt) {int rc;SampleApp *pMe = (SampleApp *)cxt;

if(pMe->m_SocketState == FALSE) { //socket is badReleaseNetAndSocket(pMe);ShowMainMenu(pMe);return;

71

}

rc = ISOCKET_Read(piSock, (byte*)buf, sizeof(buf));???br> ???br> }

When registering for network and socket events using INETMGR_InEvent(), you must de-register before terminating the application by using INETMGR_OnEvent() with bRegister = FALSE.

Please note that after the phone goes out of coverage, the sockets are unusable. You must release your ISocket(s) and reinstantiate them when next required. The INetMgr does not need to be released and re-instantiated before using it for the next network operation, however there is no harm in doing so.

To handle potentially bad sockets for asynchronous(UDP) data communication, register for change in network/socket state (described in number 2 above).

s. When I terminate a data call by closing an open socket, why does the phone still indicate that a data call is in progress? Applicable Releases: 1.0, 1.1, 2.0 After the last connected socket is closed, BREW waits for a certain linger time before terminating the PPP connection. Hence the lingering call-in-progress indication.

The default linger time is 30 seconds. To change the linger time, use INETMGR_SetLinger().

t. Why does my connect callback not timeout when service is lost (while attempting to connect) or the server does not respond? Applicable Releases: 1.0, 1.1, 2.0 This is due to a bug in the BREW version 1.0.1 SDK - connect callback is not invoked under the following circumstances: Service is lost while connect is being attempted Server does not respond

As a workaround, you should implement a timer in association with the callback. If the connect callback does not occur in 30 seconds, you should timeout the connection.

For example:

// initialize pMe->connectCBInvoked = FALSE;

// Set timer for 30 seconds before invoking ISOCKET_Connect()ISHELL_SetTimer(pMe->a.m_pIShell, 30000, ConnectTimeout_CB, (void *)pMe);ISOCKET_Connect(pMe->m_pISocket, nodeINAddr, AEE_htons(USAGE_TEST_PORT), SampleApp_ConnectCB, pMe);

72

// Set flag indicating connect CB was calledvoid SampleApp_ConnectCB(void *cxt, int err) {SampleApp *pMe = (SampleApp*)cxt;

// Set flag indicating connect CB was calledpMe->connectCbInvoked = TRUE;

if (err) {DisplayOutput((IApplet*)pMe, 3, "Connect failed!");return;}DisplayOutput((IApplet*)pMe, 3, "Connected!");

}

// When timer expires, check if connect CB was invokedstatic void ConnectTimeout_CB(void* cxt) {SampleApp *pMe = (SampleApp *)cxt;

if(pMe->connectCbInvoked == FALSE) {// Callback was not invoked within 30seconds - cancel connect callbackISOCKET_Cancel(pMe->m_pISocket, 0, 0);DisplayOutput((IApplet*) pMe, 3, "Connection timed out");

}else {// Callback invoked. Set flag to default value FALSEpMe->connectCbInvoked = FALSE;}}

u. Why is my INetMgr object NULL upon initialization using ISHELL_CreateInstance? Other objects such as IDisplay or IGraphics are initialized properly. Applicable Releases: 1.0, 1.1, 2.0 Please refer to Why does ISHELL_CreateInstance return ECLASSNOTSUPPORT when I try and create an instance of the net manager (AEECLSID_Net)?

v. What precautions should I take when I invoke INETMGR_GetHostByName() to perform DNS lookup? Applicable Releases: 1.0, 1.1, 2.0 You must ensure that your app cancels its pending DNS callback, if any, using CALLBACK_Cancel() in all exit routes. This includes when the app is suspended and when the app is stopped (both via the End key and the Clear key).

73

For example, if you used the following code to lookup a DNS address:

CALLBACK_Init(&pMe->cbkLookup, GetHostByNameCB, pMe);INETMGR_GetHostByName(pINetMgr,&pMe->dnsresult, hostName, &pMe->cbkLookup);

You should use the following code to cancel the callback in all exit routes:

// Check if the callback can be cancelled. If NULL it has // already happened and cannot be cancelled.if(pMe->cbkLookup.pfnCancel != NULL) {CALLBACK_Cancel(&pMe->cbkLookup);}

The callback cancel code should be incorporated in the Suspend event handler code ( EVT_APP_SUSPEND), the app's FreeAppData function (which is called when the app is stopped, i.e. receives EVT_APP_STOP event), and in the Clear key event handler code (EVT_KEY and keycode AVK_CLR). Please read the following article for more information: Suspending and Resuming Applications and the following FAQ for information: What difference is there between using the phone's "End" key to close an applet, and using the "Clear" key to close an applet?.

Please note that your app will not pass TRUE BREW® Testing if it does not properly cancel its pending DNS callback. Some symptoms that might indicate that your app is not canceling its p ending DNS callback are: Phone crashes upon starting up app Phone displays "Please Re-insert Battery" error upon starting up app

Both might imply that the previously running app did not cancel its pending DNS callback.

w. Are there any restrictions on what value I can set my application's network linger time to? Applicable Releases: 1.0, 1.1, 2.0 The INETMGR_SetLinger() function is provided to give developers flexibility in designing their application. However, it is not recommended that you alter the OEM's chosen default linger time (usually 30 seconds), unless your application has a compelling reason to do so. Altering the default linger time in either direction may cause your application to fail TRUE BREW Testing, or carrier rejection of your application.

Telephone API and SMSa. How do I send SMS messages from a BREW application? Applicable Releases: 1.0, 1.1, 2.0 Mobile originated SMS is supported in BREW SDK 2.0 onwards. Please refer to

74

ITAPI_SendSMS in the BREW SDK™ 2.0 API Reference Guide.

b. Can an SMS be sent to an inactive applet? Applicable Releases: 1.0, 1.1, 2.0 Yes, SMS notification events can be delivered to an application, even if it is not currently active. To do so, BREW first loads the applet, and then sends the EVT_APP_MESSAGE event to it. The application may start itself by calling ISHELL_StartApplet(), or can "silently" process the event without calling ISHELL_StartApplet().

c. How do I handle an incoming SMS message in a BREW application? Applicable Releases: 1.0, 1.1, 2.0 Please refer to this knowledgebase article Handling SMS in BREW.

d. Can SMS messages be emulated in the SDK? Applicable Releases: 1.0, 1.1, 2.0 Emulation of BREW-application directed SMS is available in BREW SDK 1.1 and onwards.

e. When making a voice call using ITAPI_MakeVoiceCall, why does my application seem to be restarted when I respond 'No' to the "Return to Application" prompt? Applicable Releases: 1.0, 1.1, 2.0 Please make sure that the parameter clsReturn (application to start when the call ends) in the call to ITAPI_MakeVoiceCall is 0 (zero). If you specify clsReturn as your app's Class ID, then BREW tries to create another instance of your app, rather than resume your app.

f. How do I obtain the phone number of the device on which my application is running?

Applicable Releases: 1.0, 1.1, 2.0 An application can obtain the phone number of the device on which it is runnng by calling ITAPI_GetStatus(). The phone number is in TAPIStatus.szMobileID.

For example:TAPIStatus tapiStat;

if (ITAPI_GetStatus(pMe->p_tapi, &tapiStat) == EBADPARM) {DisplayOutput((IApplet*)pMe, 6, "TAPI Status fetch failed");}

DisplayOutput((IApplet*)pMe, 5, tapiStat.szMobileID);

g. What is the structure of TAPIStatus.szMobileID? Applicable Releases: 1.0, 1.1, 2.0 TAPIStatus.szMobileID is an ASCII string representing the device phone number.

The first 3 digits correspond to the Mobile Country Code (MCC). For example, the MCC for

75

the United States is 310. The subsequent 2 digits correspond to the Mobile Network Code (MNC). The combination of the MCC and the MNC uniquely identify the carrier. Please note that some OEMs may pass 00000 as the MCC-MNC in TAPIStatus.szMobileID, and others may provide more meaningful values. To obtain the MCC, MNC values for a specific carrier, you will need to contact the carrier. The remaining 10 digits correspond to the area code and phone number of the device.

h. Can my BREW application be notified when there is a TAPI event, such as an incoming call? Applicable Releases: 1.0, 1.1, 2.0 You can register your app for TAPI Status Change event by modifying your MIF file:1. In the MIF Editor, select the Advanced button 2. In the Notifications box, select the Add button 3. In the Custom field, enter the hex value for AEECLSID_TAPI (the hex value can be found in BREW\inc\AEECLASSIDS.h - 0x01001007) 4. In the Mask field, enter the hex value for NMASK_TAPI_STATUS (0x00000001)5. Save the MIF file

Your app will now be notified (via EVT_NOTIFY event) when there is a change in TAPI Status, such as an incoming call. Your app must handle the EVT_NOTIFY event. For example:

case EVT_NOTIFY: {AEENotify* notifyData;TAPIStatus* tapiStatusData;

notifyData = (AEENotify *)dwParam; if(notifyData->dwMask == NMASK_TAPI_STATUS) {tapiStatusData = (TAPIStatus*) notifyData->pData;if(tapiStatusData->state == PS_INCOMING) {//Incoming call// App may wake itself up by calling ISHELL_StartApplet()}}}

Please refer to the INotify usage example for more information. TAPIStatus structure is defined in AEETapi.h.

Please note that BREW 1.0 apps should not register for NMASK_SMS_TAPI because of a BREW 1.0 bug. Please refer to Registering for NMASK_TAPI_STATUS event notification causes device to be unable to connect to Application Download Server (ADS) for more information.

76

i. To what extent is TAPI emulation supported on the Emulator? Applicable Releases: 1.0, 1.1, 2.0 TAPI emulation is included in the BREW 1.1 Emulator onwards. SDK 1.1 included emulation support for BREW application-directed SMS message, ITAPI_MakeVoiceCall and Suspend/Resume of an application by initiating a voice call.

Emulation of TAPI Status and Mobile Originated SMS is not supported.

j. How are BREW application-directed SMS messages handled when the SMS-directed application is not present on the handset? Applicable Releases: 1.0, 1.1, 2.0 If an app with the specified Class ID is not present on the handset, then the app-directed SMS is discarded.

k. What do I need to be aware of when developing applications that use BREW app-directed SMS messages? Applicable Releases: 1.0, 1.1, 2.0 In the real world (commercial handsets, not test-enabled handsets), an BREW-directed SMS message will be sent to a BREW application only if the app-directed SMS is sent from an carrier-authorized gateway or from within another BREW application (using ITAPI_SendSMS, available in SDK 2.0 onwards). This is done for security reasons, and ensures that the sender of the SMS is a trusted source.

In order to facilitate development of applications making use of this feature, we have allowed BREW applications residing on test-enabled handsets to receive BREW app-directed SMS. If you wish to use App-directed SMS on commercially deployed applications, you should contact your carrier for special access to provide this capability.

l. When making a voice call using ITAPI_MakeVoiceCall, responding 'No' to the Privacy Alert hangs the application. What is the workaround? Applicable Releases: 1.0, 1.1, 2.0 Please refer to Responding No to ITAPI_MakeVoiceCall privacy alert hangs application.

m. What guidelines should I follow when making a voice call immediately after a data call? Applicable Releases: 1.0, 1.1 Please refer to Voice call fails if made immediately after a data call.

n. When making a voice call immediately after a data call, why do I see the Privacy Alert again instead of "Return to Application"? This is due to a BREW bug in 1.x wherein the attempt to establish voice call made before the data call is properly torn down. Please refer to Voice call fails if made immediately after a data call.

77

o. How do I extract the text of a non BREW application-directed SMS message? Applicable Releases: 1.0, 1.1, 2.0 To extract the text of a non BREW-app directed SMS, you should register for NMASK_TAPI_SMS_TEXT event notification. When a non BREW app-directed SMS is received, your application will receive EVT_NOTIFY event with dwParam pointing to the pNotify data structure.

pNotify->pData is the AEESMSTextMsg. You do not need to call ExtractSMSText() on pNotify->pData as specified in the 2.0 SDK documentation.

For example:smsText = (AEESMSTextMsg*) pNotify->pData;

The text of the SMS message is in smsText->szText.

In BREW 2.0 and prior, an app that has registered for NMASK_TAPI_SMS_TEXT notification will intercept the SMS, and the native UI may not be given a chance to process it. This is OEM dependent and has serious consequence - an application that prevents SMS from appearing in the phone Inbox will cause True BREW Testing. Please refer to Why does an SMS message sent to my handset fail to appear in the phone's Inbox?" for more information.

In 2.0.2 onwards, the native UI will *always* handle the SMS. If an app is registered for NMASK_TAPI_SMS_TEXT, it will receive the notification after the native UI has handled it. So, a BREW app that has registered for NMASK_TAPI_SMS_TEXT event will be suspended when an SMS is received, if it is running. There is no guarantee as to the order of Suspend, Resume and EVT_NOTIFY events.

p. Why does a Text SMS message sent to my handset fail to appear in the phone's Inbox? Applicable Releases: 1.0, 1.1, 2.0 In BREW 2.0 and prior, an application that has registered for NMASK_TAPI_SMS_TEXT notification will intercept the SMS, and the native UI may not be given a chance to process it. This behavior in BREW 2.0 and prior is OEM dependent and varies per handset. On handsets in which BREW intercepts the SMS message, the SMS message will not appear in the Phone's Inbox, and the application will fail True BREW Testing. There is no work-around for this issue.

It is therefore important, on handsets in which SMS messages are intercepted by BREW, that applications do not register for NMASK_TAPI_SMS_TEXT notifications.

q. What settings are required to allow a running BREW application to be suspended when a non BREW SMS message is received on the Sharp Z-800? Applicable Releases: 1.0, 1.1, 2.0

78

On the Sharp Z-800 handset, you must set the following in order to receive non-BREW SMS: Main Menu -> Setup/Tool -> BREW Setting -> OFF

r. How can I remove the Privacy Alert that is displayed when making a phone call from within BREW? Applicable Releases: 1.0, 1.1, 2.0 The Privacy Alert is OEM dependent and cannot be disabled within BREW applications.

Position Locationa. What are the privacy issues regarding the ISHELL_GetPosition API?

Applicable Releases: 1.0, 1.1, 2.0 This is determined by the carrier's implementation of handling this sensitive data and by the user's personal preferences.

TRUE BREW® Testinga. What does TRUE BREW Testing involve and who will do the testing? Applicable Releases: 1.0, 1.1, 2.0 Third-party testing labs will conduct the compatibility testing. Exactly what will be tested will differ from application to application, but generally, testing will cover the following:

How the application interacts with core phone functionality. For example, how the application handles scenarios such as an instant message or other system alerts being pushed to the device while the user is in another application.

Core application stability over time. Numerous events will be sent into the event queue to see how the application handles them and to look for instability (i.e. crashes), memory usage (i.e. leaks), etc.

Major application functionality. Testing will be conducted to make sure the major functionality you claim for your application actually is in the application. QUALCOMM will not test this functionality for "correctness" from an end-user perspective.

A standard set of tests for each area of BREW functionality used by the application. For example, we will use a standard file system test suite if the application uses the BREW file system calls. Similarly, if an application uses the BREW networking calls, we will test this with a standard networking test suite.

Any carrier or manufacturer-specific look and feel requirements. Compatibility with the target device(s). Interaction with required accessories. Interoperability with a small set of core applications designated by QUALCOMM. For

example, if most of the phones in the market end up using a particular browser, we will test the submitted application to make sure it interoperates well with this browser.

Guidelines for Testing BREW Applications provides detailed information on what you should do to prepare your application for TRUE BREW® Testing.

b. What are the most common reasons why applications fail testing?

79

Applicable Releases: 1.0, 1.1, 2.0 The most common reasons why applications fail certification are listed below:

Packaging: Submit Software Application provides guidelines on how your application should be packaged prior to certification. Remember that the names of all files downloaded to the phone should be lowercase.

Signing: Often, applications are submitted with the wrong files being signed. When signing your applications using the BREW AppSigner tool, remember that you have to sign the .mod, .mif, .bar (if present) files. Other files used by the application may be signed, but only if they will not be modified at run-time. You should not be signing application specific support documents, previous test signatures or VeriSign receipts.

Modifying signed files: Files should not be modified after they have been signed using the BREW AppSigner tool. If you need to modify the signed files prior to submission for certification, you should make the modification, delete the existing signature file and repeat the signing process again to create a new signature file.

Opting to have app displayed in the Configuration menu and not handling EVT_APP_CONFIG event:In some BREW-enabled devices, you can opt to have your applet displayed on the configuration or settings menu to allow the device user to set preferences for the applet. You can do this by checking the 'Show on Config Menu' checkbox in the MIF editor (Advanced section of Applet tab). If your applet is selected from the configuration menu, it will be sent an EVT_APP_CONFIG event. Your applet must handle the EVT_APP_CONFIG event, possibly displaying a dialog box that prompts the device user to set preferences. If you do not wish to have your app displayed in the Configuration menu, please deselect the 'Show on Config Menu' selection in your MIF file.

Downloaded application package contains sub-directories:The Application Download Server (ADS) has a flat file structure, due to which an application containing sub-directories cannot be packaged for deployment on the ADS. Applications may create subdirectories at run-time; they just cannot include sub-directories in the initial download.

Not including all required images in MIF file, or submitting with incorrect image dimensions:All BREW applications are required to include the following three application images - Icon, Thumbnail and Image, each with a specific pixel dimension. Please refer to What images do I need to include in my application and what are their size requirements?.

80

Exceeding the maximum files per application limitation:Including more than the carrier-specified number of files in your application may cause your application to fail TRUE BREW Testing, or may cause carrier rejection of your application. Please refer to Are there restrictions on the number of files that can be shipped in my application?

BREW 1.x: Submitting files without application extensions:In BREW 1.x, every file included in an application submission package must have an extension. For more information please refer to Last letter of filename truncated during file download

BREW 1.x: Submitting packages with files whose filename extensions are identical but for the last letter of the filename extension:BREW 1.x: For more information please refer to Last letter of filename truncated during file download

BREW 1.x: Submitting zero-byte files in application package:Due to a BREW 1.x bug, Mobile Shop sometimes fails to download applications that contain zero-byte files. Please ensure that your application package does not include any zero-byte files. Zero-byte files pose a problem only on download - you may create zero-byte files during run-time.

Submitting application packages that contain hidden appletsIt is not possible to create an application that contains hidden applets in BREW 1.x and 2.0. This is because of the fact that the hidden application may not appear in Mobile Shop->Options and hence may be irremovable. As a workaround, please try to include the hidden applet functionality into an extension or a non-hidden (PIM, Tools, Game, etc) applet.

Incorrect Handling of Suspend/Resume:Suspend and Resume events must be handled correctly. For more information please refer to the following article: Suspending and Resuming Applications.

Data call not terminated when app is exited using the CLR Key: Network and socket resources must be released correctly, and all associated callbacks that have not yet been invoked (Read callback, Write callback, Connect callback, INETMGR_OnEvent callback, GetHostByName callback, etc) must be cancelled. If this network and socket cleanup is not done correctly, then the data call may not terminate when the CLR key is used to end the app.

Neglecting to cancel pending DNS callbacks:Pending DNS callback, if any, must be cancelled in all exit routes. For more information, please refer to NW FAQ: What precautions should I take when I invoke INETMGR_GetHostByName() to perform DNS lookup?.

81

BREW 1.0: Connect callbacks not getting fired:There is an issue in BREW SDK Version 1.0.1 wherein connect callback will not timeout under the following circumstances:

Coverage is lost when connection is being attempted OR Server does not respond

Please refer to Why does my connect callback not timeout when service is lost or the server does not respond.

Changing Network Linger Time:Changing your application's network linger may cause your application to fail TRUE BREW Testing, or may result in carrier rejection of your application. Please refer to Are there any restrictions on what value I can set my application's network linger time to?

Neglecting to verify file handle validity:When creating a file using IFILEMGR_OpenFile, you should check the returned file pointer for NULL value before accessing the file. The file pointer will be NULL if the file could not be opened. Possible reasons for not being able to open the file include 1) The maximum number of files limit has been reached on the handset, and 2) The EFS is full.

BREW 1.0: Registering for TAPI Status notification in your application's MIF file:Due to a bug in BREW 1.0, it will not be possible to register for TAPI Status notification (NMASK_TAPI_STATUS) in your application's MIF file. Please refer to Registering for NMASK_TAPI_STATUS event notification causes device to be unable to connect to Application Download Server (ADS)

Registering for NMASK_TAPI_SMS_TEXT notification:Registering for NMASK_TAPI_SMS_TEXT notification may result in your application absorbing all text SMS messages and thus preventing them from being handled by the Native UI and from appearing in the Phone's Inbox. Please refer to Why does an SMS message sent to my handset fail to appear in the phone's Inbox? for more information.

Improper use of Send Key:The Send key should only be used to perform the following actions from within a BREW application:

Make a voice call Make a data call Send a Mobile Originated SMS.

This is also documented in Section 3.8.2 of the NSTL Test Guide.

c. Are there restrictions on the number of files that can be shipped in my application? Applicable Releases: 1.0, 1.1, 2.0

82

Due to varying data structure limitations on handsets it is advisable to use as few files as possible. Some handsets have an OEM-imposed restriction on the maximum number of BREW files and it is possible to run out of available files before running out of memory.

The Sharp Z-800 handset has a BREW file limitation that requires applications to be designed to use no more than eight (8) files. This includes the files in the application package - mod, bar, sig and mif files. It also includes modules used by the application. This restriction is due to the fact that the Z-800 has a limit on the maximum number of files available to all BREW applications (93 files on the 2.01 build), which in turn places an upper boundary on the total number of applications that can fit on the handset.

Please note, that the 8 files restriction applies to the number of files used by the app when it is not running. Your app can create additional files when it runs, but must delete them when the app exits.

The current Kyocera 3035 builds allows the creation of a larger number of BREW files, in the range of 250. That being said, it would be wise to continue to limit the number of files the application uses.

Please note that including more than 8 files in your application may cause your application to fail TRUE BREW Testing, or may cause carrier rejection of your application.

d. Can I package several bar files in my BREW application, one for each target device? Applicable Releases: 1.0, 1.1, 2.0 You can package your application with more than one resource (bar) file. When your application is downloaded to the handset, all the bar files will be downloaded along with it. Based on some criteria (such as Color Depth or Platform ID obtained using ISHELL_GetDeviceInfo), you can choose to load resources from a particular bar file.

e. How do I package Multiple Modules into a Single True BREW Testing Submittal? Applicable Releases: 1.0, 1.1, 2.0 If you are submitting an application that consists of Multiple Modules, please structure the zip file as described below:

Each "mod" file must have a unique name. The Developer should put each "mod" file within separate sub-directories under the ARM directory. Each sub-directory should have it's own "mod" and "mif" files and be signed separately. The name of the sub-directory and associated "mod" file should be the same. For example:

ARM\test1\    test1.mod    test1.mif    test1.sig    test1.bar

83

    ARM\ test2\    test2.mod    test2.mif    test2.sig etc... The same directory structure used for the ARM directory should be used for the WIN directory. The windows version of the application is also used for testing and should be based on the same modules used for the phone.

f. I am using application preference files. Will I have to sign my application with the Modifiable flag? Applicable Releases: 1.0, 1.1, 2.0 Since storing application preferences does not modify any of the application's files, the application does not have to be signed with the Modifiable flag.

Known Issues - BREW SDK™, Tools, BDS Known Issues1. SDK 1.0 KNOWN ISSUESa. Bug in ExtUse and Extensions example Applicable Releases: 1.0, 1.1, 2.0 The ExtUse and Extensions example shipped in the BREW SDK 1.0 contains the following bugs in the MIF files: 1. All privileges are checked (You do not need all privileges in order to load an extension)2. The Extension's Class ID is listed under both 'Exported Classes' and 'Applet Information'

This is fixed in the 1.1 SDK.

b. GET_JULIANDATE() works on the emulator, but not on the phone. Applicable Releases: 1.0 The JulianType data structure filled by this function populates wWeekDay field differently on the emulator and on the handset. In the emulator, wWeekDay takes on the values (0..6), where 0 = Sunday and 6= Saturday. On the handset, wWeekDay takes on the values (0..6), where 0 = Monday and 6= Sunday.

This has been fixed in BREW 1.1 - in BREW 1.1, both the emulator and the handset return JulianDate.wWeekDay with the values 0..6, where 0 = Monday and 6 = Sunday.

Workaround for version 1.0:In BREW 1.0, the following code will ensure that the emulator and handset give the same result.

GET_JULIANDATE(0, &julian);

#ifdef AEE_SIMULATORif (julian.wWeekDay == 0)julian.wWeekDay = 6;

84

elsejulian.wWeekDay --;#endif

c. Number of Uses License is reset when phone is power-cycled Applicable Releases: 1.0 License information is stored in the MIF file. When an app calls ILICENSE_SetUsesRemaining(), ILICENSE_DecrementUsesRemaining or ILICENSE_IncrementUsesRemaining(), BREW attempts to update the MIF file. Due to a bug in BREW SDK version 1.0.1, the app must have File Privilege level in order for the MIF file update to succeed. The work-around for SDK 1.0.1, therefore, is to include File Privilege level (via the MIF editor). This has been fixed in SDK version 1.1, i.e., usage-based apps do not need to have File Privilege level in 1.1.

d. Registering for NMASK_TAPI_STATUS event notification causes device to be unable to connect to Application Download Server (ADS) Applicable Releases: 1.0 BREW 1.0 applications should not register for TAPI Status Change event (NMASK_TAPI_STATUS) in the application MIF file due to the following BREW 1.0 bug:

Consider an application that is registered for NMASK_TAPI_STATUS in its MIF file and has been disabled.

When Mobile Shop is next launched, it will connect to the ADS. Starting Mobile Shop causes TAPI Status change event to be sent to disabled app. Since the app is disabled, BREW starts Mobile Shop in order to re-enable it, which in turn sets off another TAPI Status change event, and so on in a loop. This prevents the device from connecting to the ADS until the application is either enabled or removed.

There is no workaround to this issue - BREW 1.0 apps cannot register for TAPI Status Change event in the app's MIF file. To be informed of TAPI Status change events while your app is running, you can use ISHELL_RegisterNotify().

2. SDK 1.X KNOWN ISSUESa. Last letter of filename truncated during file download Applicable Releases: 1.X In BREW 1.x, every file included in an application submission package must have an extension. When a package is downloaded to a phone in 1.x versions of BREW, the last character of the extension name is replaced with ~ and stored. Therefore, a file named xxx.bar is stored as xxx.ba~ and a file named xxx.bak is also stored as xxx.ba~. The list is then searched sequentially based on all the characters of the extension name up to the last letter. Accordingly, only two letters are searched for three-letter extensions; only three letters are searched for four-letter extensions, and so on. The first match in the list is used. For example, if the first match is xxx.bar, all files with three-letter extensions beginning with ba are

85

changed to extension BAR.

A file name that does not include an extension has the last letter of the file name truncated upon download. Therefore, the file name myfile became myfil in the application package.

WorkaroundDevelopers must adhere to the following guidelines in naming files for their applications:

1. When possible, avoid using file names that are identical except for the last letter of the extension.

2. If you must have file names that cannot comply with the previous guideline, consider adding an extra character to the file extension and then removing the extra character at runtime.

For example, a package contains the following files: myapp.mifmyapp.barmyapp.modmyapp.sigmyapp.bak_myapp.mid_

The underscore character (_) has been added to the BAK and MID files to avoid confusion with the MIF and BAR files during sorting, as described in the Problem section above. To remove the extra characters the first time the application is executed, use the IFILEMGR interface to search for the affected files and rename them.

NOTE: You will be able to do this only if you identified the files as "changeable during run time" using the BREW AppSigner tool.

3. Do not use a file name without an extension. This especially impacts applications that include database files as part of their submission package.

On the Emulator and most handsets, creation of a database named "foo" results in the creation of two files: a database file without an extension name (foo) and an index file with an idx extension (foo.idx). This poses a problem in BREW 1.x, since every BREW 1.x file must have an extension. It is not possible to create a database name with an extension, such as "foo.db", since BREW 1.x does not allow multiple file name extensions (foo.db.idx is not possible in 1.x).

The workaround is to rename the database before submission by giving it a dummy extension such as .dbf. Foo may thus be renamed foo.dbf before submission. The app will then need to rename the database name during runtime by removing the dummy extension (changing

86

foo.dbf to foo before performing database operations).

For example:// Please note that this is sample code and does not perform all exhaustive error checking.

// Check if foo.dbf existsif(IFILEMGR_Test(pIFileMgr, "foo.dbf") == SUCCESS) {// check if foo" exists. If so, remove itif(IFILEMGR_Test(pIFileMgr, "foo", &fInfo) == SUCCESS) { if (IFILEMGR_Remove(pIFileMgr, "foo") == EFAILED) {// cannot remove "foo". Database operations will not succeed.return;s}}

//rename by removing extensionif(IFILEMGR_Rename(pIFileMgr, "foo.dbf", "foo") == SUCCESS) {// Successfully renamed// Proceed with database operations: IDATABASE_Open(.., "foo", ..)}else { ?.}}else { ?.}

Please note that you should not sign the database files (using BREW AppSigner tool) when submitting, since the workaround renames the database files.

On the Kyocera 3035, the database (foo) is created as foo.dat and foo.idx. In this case, you do not need to do anything special in your code. IDATABASE_Open(.., "foo", ..) will work. Keep in mind that you cannot create the database on the emulator (without extension), then add .dat extension when transferring to the phone. The database open on the phone will fail.

In BREW 2.0, the issue is resolved since 1) Multiple file name extensions are allowed2) Only the MIF file will be truncated and appended with ~ during download

Therefore, it will be acceptable in BREW 2.0 to have extension-less file names.

b. Voice call fails if made immediately after a data call Applicable Releases: 1.X This is a bug in BREW 1.x. After the last socket is released, BREW waits for the network linger time (default linger time is 30s) to expire before terminating the PPP connection. The

87

actual tearing down of the PPP connection takes about 3s. Therefore, (linger time + 3 seconds) must elapse between releasing the last socket and invoking ITAPI_MakeVoiceCall(). You should introduce a (linger time + 3 seconds) timer between releasing the last socket and making the voice call.

For example:

ReleaseNetAndSocket(pMe);

//LINGER_TIME below is in secondsISHELL_SetTimer(pMe->a.m_pIShell, (LINGER_TIME +3) * 1000, Timer_CB, (void *)pMe);

In the timer callback code, you can make the voice call using ITAPI_MakeVoiceCall().

Please refer to the following FAQs for more information on ITAPI_MakeVoiceCall(): After making a voice call using ITAPI_MakeVoiceCall, why does my application seem to be restarted when I respond 'No' to the "Return to Application" prompt? and When making a voice call using ITAPI_MakeVoiceCall, responding No to the Privacy Alert hangs the application. What is the workaround?

Note: In BREW SDK version 2.0, this 3-second lag is built into BREW. The application will not need to implement the additional 3 seconds in its timer.

c. Generic BREW icon/thumbnail/image is saved in MIF file if full image path is not specified when MIF file is saved. Applicable Releases: 1.X To save an image in a MIF file, you need to browse to the location of the image file on your PC and select it. After doing this, you will see the full path of the image file in the MIF Editor. The next time you open the MIF file, you will see "" instead of the path to the image. This is the expected behavior.

If you used the 1.x MIF Editor to save a MIF file whose icon/thumbnail/image contained the value "", then the BREW Application Manager would display the generic BREW icon/thumbnail/image instead of the images contained within the MIF file. This is due to a bug in the 1.x MIF Editor. It has been fixed in the 2.0 MIF Editor.

There are two possible workarounds: 1. Ensure that the icon, thumbnail and image values are set to the full path of the image rather than "" each time you save the MIF file using the 1.x MIF Editor. That is, browse to the full path of the images each time you save the MIF file. 2. Use the 2.0 MIF Editor to save your 1.x MIF file. This can be done using File->Save and selecting the type as "BREW Module Information Files v 1.00". When using 2.0 MIF editor, you will not need to browse to the full path of the images each time you save the MIF file.

88

d. Preferences not removed when application is removed Applicable Releases: 1.X Version 1.0.1 has a bug in the removal of preferences: preferences set using ISHELL_SetPrefs() are not removed when the application is removed. This has been fixed in BREW Version 1.1.

3. SDK 1.x, 2.0 KNOWN ISSUESa. Responding No to ITAPI_MakeVoiceCall privacy alert hangs application Applicable Releases: 1.X, 2.0 The recommended workaround is for the user to press 'No' twice (i.e. press Select Key twice). When the Privacy Alert Yes/No dialog is displayed, all key events up until the first Select key press go to the Dialog. After the first Select key (for the dialog), subsequent key events go to the application.

Steps are outlined below:1. Added a boolean 'madeVoiceCall' in the Applet structure2. If ITAPI_MakeVoiceCall() returns Success, set madeVoiceCall to TRUE

retValue = ITAPI_MakeVoiceCall(pMe->p_tapi, PHONE_NUM, AEECLSID_SAMPLEAPP);ITAPI_Release(pMe->p_tapi);if(retValue == SUCCESS) {pMe->madeTapiCall = TRUE;}

3. Handle EVT_KEY in the app handler function. If the Select key was pressed and madeVoiceCall is TRUE, the user has selected No in response to the Privacy Alert. Set madeVoiceCall = FALSE and redraw screen.

case EVT_KEY:if (wParam == AVK_SELECT && pMe->madeTapiCall == TRUE) {// Redraw screenpMe->madeTapiCall = FALSE;}return TRUE;

4. If the user selected 'Yes' to the Privacy Alert, the application would have been suspended. When resumed, the madeVoiceCall flag must be cleared.

case EVT_APP_RESUME:if(pMe->madeTapiCall == TRUE) {pMe->madeTapiCall = FALSE;}

89

???br> ???br> return TRUE;

b. GETTIMEMS() works on the emulator, but not on the phone. Applicable Releases: 1.X, 2.0 There is a bug in GETTIMEMS() and ISHELL_GetTimeMS() in BREW versions 1.x and 2.0. This will be fixed in a subsequent version of BREW. In the meantime, you can use the following workaround to get time:

JulianType julianDate;uint32 timeInSeconds;uint16 hour, min, sec;char timeBuf[30] = {0};

GET_JULIANDATE(0, &julianDate);

hour = julianDate.wHour;min = julianDate.wMinute;sec = julianDate.wSecond;

SPRINTF(timeBuf, "Time: %u:%u:%u", hour, min, sec);

90