API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

ISHELL

Brew Release
Brew MP 1.0.2
Description

The functions in the IShell interface provide a variety of services to Brew MP applications. This section includes a high-level overview of the IShell interface functions, with each subsection describing a group of related functions.

Alarms


The AEE shell’s alarm functions enable an application to be notified when the current time reaches a specified value. Unlike timers, which can be active only while your application is running, you can receive notification that an alarm has expired even when your application is not running. Alarms are typically used when the time of notification is in the distant future. For example, a calendar application uses an alarm to alert the user when a calendar appointment is about to be reached.
To set an alarm, you call ISHELL_SetAlarm() and specify the number of minutes from the current time at which the alarm notification is to occur, a 16-bit alarm code, and the Brew MP classID of the application (yours or another) that receives notification when the alarm time is reached. At notification time, the IAPPLET_HandleEvent() function of the notified application is called with an EVT_ALARM event and the 16-bit alarm code as parameters. The latter parameter allows an application to distinguish between more than one simultaneously active alarm. If the notified application is not currently running, the AEE Shell creates an instance of it to process the notification event, after which it is terminated. The application may choose to activate itself if necessary. The AEE Shell stores alarms in a Brew MP database and continuously checks for alarm expirations while the Brew MP-enabled device is turned on. If an alarm’s expiration time passes while the device is turned off, the AEE Shell generates the notification the next time the device is turned on.
ISHELL_CancelAlarm() cancels a currently active alarm. ISHELL_AlarmsActive() checks whether any of the Brew MP built-in annunciators (alarm clock, countdown timer, or stopwatch) is currently active.

Application management


The AEE shell’s application management functions have a number of purposes, including the following:
- Creating, starting, and stopping Brew MP classes and applications.

- Obtaining information about the modules and classes that are present on the device.

- Allowing applications to send events to each other.

- Allowing Brew MP applications to run without interfering with other activities
that the device must perform.
ISHELL_CreateInstance() creates instances of both Brew MP classes and of user-defined classes supported by the modules present on the device. ISHELL_StartApplet() allows a specified applet to run. It creates an instance of the applet if necessary, suspends the currently running applet (if any); and then invokes the specified applet’s IAPPLET_HandleEvent() function with the EVT_APP_START event, which allows it to run. ISHELL_CloseApplet() sends the currently running applet the EVT_APP_STOP event and calls its Release() function. ISHELL_CloseApplet() is used primarily by the AEE shell itself.
ISHELL_ActiveApplet() is used to obtain the classID of the applet that is currently top-visible. ISHELL_EnumAppletInit() and ISHELL_EnumNextApplet() can be used to enumerate the applets in the modules that are present on the device. As each applet is enumerated, ISHELL_EnumNextApplet() returns a pointer to an AEEAppInfo data structure for the applet, which identifies the applet’s MIF file, titles, icons, and type (such as game, tool, PIM, or other type). ISHELL_QueryClass() determines if a particular class is available on the device. If the class is an applet, supply a pointer to an AEEAppInfo data structure, which is populated with the relevant information if the applet is available.
Use ISHELL_SendEvent() to send an event to a specified class. 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 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. ISHELL_HandleEvent() is used when the identity of the class that is to receive the event is not known. In this case, the AEE shell sends the event to the currently running applet or its active dialog, if any.
The AEE shell includes several functions that enable Brew MP applications to coexist with other activities on the device. The Brew MP application model is based on cooperative multitasking, which means that each application must be designed to run for as short a time as possible when processing an event, and then exit to give other device activities a chance to run.
ISHELL_Busy() lets a Brew MP application determine whether any activities are in progress on the device that requires it to exit immediately. ISHELL_ForceExit() is identical to ISHELL_Busy(). ISHELL_Resume() allows an application to break time-consuming tasks into smaller, interruptible chunks. Each chunk is represented by a callback function and an associated data pointer. Calling ISHELL_Resume() schedules the callback function to be invoked at a later time with the data pointer as its only parameter. Use ISHELL_CanStartApplet() or IAppletCtl_Control() to check whether it is possible to start a Brew MP application, which may not be true if higher priority activities are in progress on the device.

Dialogs, message boxes, and prompts


A dialog consists of a screen containing one or more Brew MP controls that allow the device user to enter data or select an item from a menu. Although you may create such a screen with the Brew MP control interfaces (IDateCtl interface, IMenuCtl interface, ITextCtl interface, and ITimeCtl interface), IDialog interface simplifies this task:
- Create a dialog using the Brew MP Resource Manager, including specification of
each of the controls in the dialog. See the Brew MP Resource Manager Guide for more information.
- The Brew MP AEE (application execution environment) maintains a stack of the dialogs associated with the currently
running application. When you create a dialog, it is placed at the top of the stack; when a dialog ends, it is removed from the stack and the dialog below it is restored. This makes it easy to implement applications that step the device user through a sequence of screens (such as a menu hierarchy).
- When a dialog is active, it receives all events and distributes them to the
currently active controls. The dialog also handles control tabbing, which allows the device user to move between controls in a multicontrol dialog. This frees you from having to implement code to distribute and handle these events.
Use ISHELL_CreateDialog() to create a dialog. This function accepts either the identifier of a dialog you have created in the Brew MP Resource Manager or a pointer to a data structure that you populate in your code to specify the controls in the dialog. If successful, the function shows the dialog’s controls on the screen and pushes it onto the dialog stack. To end the dialog, you call ISHELL_EndDialog(), which terminates the dialog at the top of the stack and shows the dialog immediately below it on the stack. This function also sends the EVT_DIALOG_END event to your application, which allows you to perform any processing associated with the dialog’s termination, such as retrieving values entered by the device user in the dialog’s controls. ISHELL_EndDialog() also frees all the resources that are being used by the dialog.
ISHELL_CreateDialog() does not return an interface pointer to the dialog it creates. ISHELL_GetActiveDialog() is used to obtain an IDialog interface pointer for the dialog at the top of the stack. Use this pointer to invoke the functions that comprise the IDialog interface: IDIALOG_GetControl(), which returns interface pointers to any of the dialog’s controls, and IDIALOG_SetFocus(), which is used to specify which control in a multicontrol dialog receives input from the device user.
The AEE shell also provides functions that can be used to create simple, commonly used dialogs with a single function call. ISHELL_Prompt() shows a dialog with a Soft Key control menu that prompts the device user to make a selection. When the device user does so, the selection is returned to your application using an EVT_COMMAND and the dialog is automatically terminated. There are also two functions that create a dialog that shows a read-only text message and title. ISHELL_MessageBox() reads the title and message text from a Brew MP resource file, while ISHELL_MessageBoxText() accepts pointers to title and message text strings that you specify in your code. The dialogs created by these functions end when the device user presses a key.

Device and application configuration information


These functions allow configuration information about the device and specific applications to be obtained. ISHELL_GetDeviceInfo() returns a pointer to an AEEDeviceInfo structure for the device, which includes information about its screen size and color support, amount of available memory, character encoding, and other items.
ISHELL_GetPrefs() and ISHELL_SetPrefs() provide a general-purpose mechanism for applications to register configuration information. Use ISHELL_SetPrefs() to associate a pointer to configuration data and a version number for this data with the ClassID of your application. Other applications can obtain this data by calling ISHELL_GetPrefs() with the specified ClassID and version number. You also must provide a structure declaration that defines the content of each version of your application’s configuration data.

Miscellaneous


ISHELL_Beep() allows an application to provide several types of audible or vibrating signals to the device user. Depending on what a given device supports, there are audible signals that correspond to device-off, alert, reminder, message arrival and error events, and vibrating signals for alerts and reminders. There is also a Boolean loudness parameter that can be specified.

Notifications


IShell’s notification mechanism allows a Brew MP class to notify other classes that certain events have occurred. A class activated to receive a notification must register its interest with the AEE Shell specifying the ClassID of the notifier class and the events for which notification is specified. When an event requiring notification occurs, the notifier class calls ISHELL_Notify(), which sends notification to each class that has registered to be notified of the occurrence of that event.
The AEE Shell provides two ways for a class to register for notification of an event:
- Register by specifying information about the notification in your application’s
MIF file using the MIF Editor. This method of registering is used by applications that must be notified of events even when they are not running. One example is a call-logging application that receives notification of each incoming and outgoing call. Such an application needs to process notifications even while the device user is not running the application to display the call log.
- If notification is required only at certain times while your application is
running, call ISHELL_RegisterNotify() to initiate event notification. For example, a game application might display a message when an incoming call arrives that allows the device user to accept the call or continue playing the game. This application requires notification of incoming calls only while the device user is actually playing the game, so it calls ISHELL_RegisterNotify() when the device user starts to play the game.
The events for which a notifier class provides notifications are represented by a 32-bit variable. The low-order 16 bits of this variable contain the notification mask with each bit corresponding to one event. The high-order 16 bits contain the notifier match value, which can be used for data associated with an event. For example, events representing activity on a UDP socket use the match value for the port on which the activity has occurred. When it registers for notification, a class provides a value for the mask variable with the bit for each event of interest set to 1. If a class no longer requires notification of an event, it can call ISHELL_RegisterNotify() with that event’s bit set to 0 (zero) in the mask variable. For example, an application might call ISHELL_RegisterNotify() with the mask variable set to 0 (zero) upon termination.
NOTE: The AEE Shell creates an instance of the notifier class when another class registers for notification of its events. This instance is released when all classes have unregistered for event notification.
When a notifier class calls ISHELL_Notify(), the AEE Shell sends an event of type EVT_NOTIFY to each application that has registered for the event. This results in the invocation of the application’s IAPPLET_HandleEvent() function. If the application is not currently running, the AEE Shell creates an instance of it to process the event, after which the application terminates. The application can send itself a start event to continue running. In the call to IAPPLET_HandleEvent(), the application also is passed a pointer to a structure of type AEENotify, which identifies the event that occurred, the class that generated the notification, and some additional data specific to the notification.
At present, the INetMgr class sends notifications to other interested classes of changes in the network connection state and the arrival of data on particular UDP ports. You can also implement your own notifier classes. Your class must implement the INotifier Interface (see the sample notifications application for details on how to declare this interface when defining your class). The INotifier Interface requires you to implement a INOTIFIER_SetMask() function for your class. The AEE Shell calls this function whenever another class registers for event notification from your class. INOTIFIER_SetMask() has a single argument, which is a 32-bit variable that is the logical OR of the mask variables that each class used when it registered for notifications from your class. This variable has a value of 1 for a bit if at least one class has registered for notification of the corresponding event. You can use this variable to perform any initialization needed when a class first registers to be notified of an event, and any finalization when there are no longer any classes requiring notification of a particular event.

To provide notifier functionality in your class

1. Provide an include file that contains constants defining the bits assigned to each notification event, and typedefs for the event-specific data that is provided as part of an event notification. This include file is used by applications that register for notifications from your class.
2. Call ISHELL_Notify() whenever a notification event occurs and at least one class has registered to be notified of that event’s occurrence.

Resource files and file handlers


The AEE Shell provides a number of functions that your application can use to read various types of data from files. These files can be Brew MP resource (.bar) files created with the Brew MP Resource Manager, or they can be files whose content is associated with a MIME type or identified by the file’s extension. You can also extend the set of file types that the Brew MP AEE recognizes by defining your own handler classes and using them to manipulate files of particular MIME types.
Use the following functions to access Brew MP resource files. Each function’s parameters include the name of the resource file and the integer resource ID:
- ISHELL_LoadResData() loads resources other than strings and bitmap images.
At present, these include several resource types associated with dialogs. The memory used to store the resource information is freed by calling ISHELL_FreeResData().
- ISHELL_LoadResImage() loads a bitmap image from a specified resource file
and returns a pointer to an instance of the IImage Interface that contains the bitmap. IIMAGE_Release() frees the data used to store the bitmap.
- ISHELL_LoadResObject() implements the sound and image loading functions. ISHELL_LoadImage(),
ISHELL_LoadResImage(), ISHELL_LoadSound(), and ISHELL_LoadResSound() are all macros that invoke this function with different parameters.
- ISHELL_LoadResSound() loads a sound resource from the specified resource file
and returns a pointer to an instance of the ISoundPlayer Interface that contains the sound file. ISOUNDPLAYER_Release() frees the data used to store the sound data.
- ISHELL_LoadResString() reads a string resource into a character buffer, a
pointer to which is one of the function’s arguments.
ISHELL_LoadImage() and ISHELL_LoadSound() can be used to load image and sound files directly without first placing their contents into a Brew MP resource file. The files must contain one of the built-in MIME types supported by the Brew MP AEE, which include Windows bitmap (BMP) or a device-specific native bitmap format for images and MIDI (.mid) or CMX (.pdm) sound files.
Use ISHELL_RegisterHandler() to associate a MIME file type with the ClassID of the Brew MP handler class you have implemented to handle files of that type. ISHELL_GetHandler() returns the ClassID of the handler class associated with a given MIME type, including the Brew MP built-in types mentioned above.
Call ISHELL_GetHandler() to get the ClassID of the handler class for the file’s MIME type.
Call ISHELL_CreateInstance() to create an instance of the handler class.

Timers


The AEE Shell’s timer is used by a currently instantiated application (an application whose reference count is non-zero) to perform an action when a specified amount of time has passed. These time periods are typically short (seconds or milliseconds). Use the AEE Shell’s alarm functions to obtain notification when longer time periods have passed, even when your application is not currently instantiated.
To start a timer, you call ISHELL_SetTimer() and specify the timer duration in milliseconds, the address of a callback function, and a pointer to an application-specific data structure. When the timer expires, the AEE Shell calls the callback function with the application-specific data pointer as its only parameter. Brew MP timers are one-time, nonrecurring timers, so it is not possible to specify a timer that repeats at a fixed interval. However, to obtain this behavior, call ISHELL_SetTimer() within your callback function and specify the function’s own address as ISHELL_SetTimer()’s callback function parameter.
ISHELL_GetTimerExpiration() can be used to determine the number of milliseconds remaining before a particular timer expires. A timer is identified by the callback function and data structure addresses supplied when it was created. ISHELL_CancelTimer() cancels a running timer. If a NULL value is supplied for the callback function parameter, all timers associated with the specified data structure address are canceled. When an application instance’s reference count drops to 0 (zero), all timers associated with that application are canceled.
Methods