BREW开发教程(7):BREW应用开发基础

“Hello,world”应用仅仅是一个极其简单的程序，实际开发BREW应用要比这个复杂得多。学会使用BREW编程，首先必需了解BREW API提供了哪些接口可供开发者使用，并了解BREW应用的程序框架。本章介绍开发BREW应用必需了解的几个核心接口、程序入口点、BREW提供的桩代码以及推荐使用的应用程序开发框架。

程序入口点

在BREW应用程序管理器启动一个Applet时，它会首先调用由Applet提供的AEEClsCreateInstance函数。所用的Applet都必需以同样的名称及参数列表提供这个入口函数，这个函数相当C中的main () 函数。

函数原型定义如下：

int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * po,void ** ppObj)

参数：

ClsID：     ［输入］提供了与Applet对应的唯一的Class ID。

pIShell： ［输入］提供了指向IShell接口的指针。

po：          ［输入］提供了指向当前模块的IModule指针。

PpObj:  [输出] 返回指向IApplet结构的指针。

实际上AEEClsCreateInstance函数是由BREW平台来调用，前面的三个输入参数是由BREW平台来传入的，而不需要Applet 来关心。

在这个函数中Applet需要调用AEEApplet_New函数来为Applet分配内存及初始化消息处理函数及Applet退出时的清除函数。参见”Hello,World”示例。

这部分的代码是大同小异的，函数的返回值，为AEE_SUCCESS表Applet被成功创建，而返回EFAILED表明不能正常创建Applet，应用将退出。

BREW SDK桩代码

在BREW SDK开发包中的src子目录中有几个C源代码文件，其中最常用的为AEEModGen.c和AEEAppGen.c。这两个文件提供了对IApplet和IModule接口缺省实现。函数AEEApplet_New也包含在AEEAppGen.c中。

这个函数用于为Applet创建AEEApplet结构，一般必需由AEEClsCreateInstance来调用。

函数原型定义：

boolean AEEApplet_New(int16 nSize,

AEECLSID clsID,

IShell * pIShell,

IModule * pIModule,

IApplet **ppobj,

AEEHANDLER pAppHandleEvent,

PFNFREEAPPDATA pFreeAppData)

参数说明：

参数说明nSize指明了需要为Applet分配内存的大小，通常情况下，Applet必定义自已的结构，比如CSocketApp，这个结构必需将AEEApplet作为它的第一个成员变量。应用程序结构包含与应用相关的成员变量。整个结构(CSocketApp)的大小由该参数传入。clsID提供了与Applet对应的唯一的Class IDpIShell提供了指向IShell接口的指针PIModule提供了指向当前模块的IModule指针ppobj返回指向应用程序结构(CSocketApp)的指针pAppHandleEvent指向Applet事件处理器的函数指针pFreeAppData指向Applet清除函数的函数指针

如果使用应用程序向导来创建的Brew应用，在程序工程中会自动加入这两个桩文件，如果自行创建工程，则需要将BREW的这两个桩文件添加到工程中，否则会造成编译及链接错误。

IApplet接口

IApplet接口是在AEE环境下处理事件的接口, 它是从IBase接口的派生接口, 并且只提供了一个用于事件处理的例程, IShell接口将调用这个例程用于响应系统、其它组件或其它Applet发出的消息, BREW中所有的Applet都必需实现这个接口定义了函数，换句话说，BREW的Applet就是实现了IApplet接口，IAPPLET_HandleEvent()就是被IShell接口用来向Applet传递事件消息的。

注意：IAPPLET_HandleEvent()只能被IShell来调用，其它部件或Applet可以通过调用ISHELL_SendEvent()来发送事件消息。

IAPPLET_HandleEvent()

这个函数提供对BREW Applet主事件处理，当有消息发送给Applet被IShell调用，事件可以包括系统级通知、键盘事件等。

系统级通知及告警也会调用这个函数来响应通知和告警，如果Applet当前不处于活动状态，那么将应动这个Applet然后将消息发送给它，除非Applet是自已启动而不是唤起的，否则EVT_APP_STOP事件将不会发送给Applet，Applet在收到这个消息之后会终止运行。所有的Applet都必需实现这个函数。

IAPPLET_HandleEvent()函数也用作支持Applet启动、终止、暂停、恢复。

函数原型：

boolean IAPPLET_HandleEvent

(

IApplet * pIApplet,

AEEEvent evt,

uint16 wp,

uint32 dwp

)

参数说明：

pIApplet 指向Applet的指针.

evt 事件代码

wp 16-bit 事件参数

dwp 32-bit 事件参数。

返回值：

TRUE，Applet处理过该事件。

FALSE，Applet不处理该事件。

注意：如果Applet不处理某个事件，一定要返回FALSE，以使得AEE可以进一步处理该事件。一个典型例子是响应AVK_CLR键盘事件，如果Applet不想响应该事件，返回FALSE，AEE将关闭该Applet。

IShell接口

IShell接口提供了大量的函数可供BREW应用使用。

Alarm事件

AEE Shell接口的告警功能使用Applet在时间到达某个特定点收到告警通知消息，和定时器不同的是，定时器只能在Applet处于活动状态时才能使用，Applet即使是在非活动状态时也可以收到Alarm事件。Alarm事件的典型用法是在未来的某个时间收到这个事件，比如，一个日程表应用在一个约会前可以使用Alarm事件来通知用户该约会快到期了。

可以使用ISHELL_SetAlarm()函数来设定一个Alarm事件。通过指定一个16位告警消息号和设定从当前时间开始延迟的分钟数以及需要收到Alarm事件的Applet的Class ID为Alarm函数指定参数。当到达指定的告警事件时，被通知的Applet的IAPPLET_HandleEvent()将被调用，其主事件为EVT_ALARM，从事件号则为设定的告警事件号。最后一个参数可以是Applet用来区分同时处于活动状态的两个Alarm事件。如果该Applet当前不处于活动状态，AEE将创建该Applet的一个实例，并将该Alarm事件传给它。Applet实例处理完该消息后则退出，也可以根据需要使自已保持活动状态。AEE Shell将告警事件存在数据库中并在设备打开时定时检测是否有Alarm事件到期，如果设备处理关闭状态时有Alarm事件到期，则该事件在设备下次打开时被激活。

ISHELL_CancelAlarm()取消当前处于活动状态的Alarm事件，ISHELL_AlarmsActive()用于判断BREW内嵌的任何一个预报消息（Alarm时钟、Countdown定时器、Stopwatch）是否处于活动状态。

应用程序管理

AEE Shell提供的应用程序管理功能具有以下目的：

• 创建、启动、停止BREW类和Applet。
• 取得设备上关于模块、类的有关信息。
• 提供应用相互之间发送消息的机制。
• 允许BREW应用在不影响设备其它活动时正常运行。

ISHELL_CreateInstance()用于创建BREW提供的类或是设备上用户定义的模块中类的实例。ISHELL_StartApplet()允许某个Applet运行。如果有必要的话将停止正在运行的Applet，去创建新Applet一个实例。然后调用这个Applet的IAPPLET_HandleEvent()并向其发送EVT_APP_START消息，允许Applet开始运行，ISHELL_CloseApplet()向当前正在运行的Applet发送EVT_APP_STOP消息并调用Applet清除函数。ISHELL_CloseApplet()只能被AEE Shell调用，一个Applet试图去停止另一个Applet是行不通的。

ISHELL_ActiveApplet()取得当前正在运行的Applet的Class ID。ISHELL_EnumAppletInit() 和 ISHELL_EnumNextApplet()用于枚举设备中模块中所有的Applet。在枚举的过程中，函数和 ISHELL_EnumNextApplet()返回该Applet的指向AEEAppInfo结构的指针，该结构定义了该Applet的MIF文件、图标、类型（游戏、工具、PIM或其它类型）。ISHELL_QueryClass()用于检索指定的类是否存在于设备上。如果这个类是一个Applet，则返回一个的指向AEEAppInfo结构的指针。

调用ISHELL_SendEvent()函数向指定的类发送消息，如果该类不存在实例，AEE Shell将创建该实例将调用其IAPPLET_HandleEvent()并将指定的消息号传给它。除非Applet选择启动自身，否则在处理完该消息后Applet将退出运行。ISHELL_PostEvent()具有类似的功能，只是不是马上调用目标Applet的IAPPLET_HandleEvent()。该消息被放置在消息队列中稍后发出。也可以称为导步发送消息。使用得发送消息的Applet可以继续运行。ISHELL_HandleEvent()用于发送至的Applet身份无法确认时，此时AEE Shell将向当前活动的Applet或是处于活动状态Dialog发送该消息。

AEE Shell包含了几个可以用来使几个Applet在设备协调工作的函数。BREW平台提供的是合作式多任务方式。这意味着Applet应用被设计成尽可能以最短的时间运行，在处理完消息后，退出以使其它活动得以进行。

使用ISHELL_Busy()Applet可以知道设备是否有某种活动并要求自已退出运行。ISHELL_ForceExit()具有相同的功能。

ISHELL_Resume()允许应用程序将一个耗时的任务分解成多个小的可中断的片断，每个片断可由一个回调函数和与之关联的数据指针表示。调用ISHELL_Resume()在稍后的时间中调用回调函数ISHELL_CanStartApplet()用于是否可以启动一个Applet,如果这时有一个高优先级的进程正在运时，该函数将返回FALSE。

对话框、消息框和提示

对话框可以包含一个或多个BREW控件允许接收用户输入或选择某个菜单项。尽管你也可以通过BREW控件接口来创建类似的窗口。但IDialog接口使这个工作变得更为简单。

• 通过创建资源文件在其中给出每个控件的规格。
• BREW AEE为一个正在运行的Applet维护一个对话框堆栈，当创建一个对话框时，它将被置在这个堆栈栈顶。结束一个对话框时，它将从堆栈中删除，其下对话框被显示。
• 当一个对话框处于活动状态时，它将接收消息并将它们分发到当前对话框中活动的控件，对话框同时也处理Tab事件，从而允许设备用户在一个多控件对话框中从一个控件移到到另一个控件。而不需要开发者另行写代码来完成这部分工作。

使用ISHELL_CreateDialog()来创建一个对话框，可以通过指定资源文件中对话框ID或是通过填充一个数据结构来创建这个对话框。如果创建成功，将在屏幕上显示这个对话框，并将它加入到对话框堆栈中。ISHELL_EndDialog(),用于关闭一个堆栈顶的对话框显示其下的对话框。同时向Applet发送EVT_DIALOG_END事件，允许开发者处理对话框中止时任务，比如从对话框中取得用户输入等。ISHELL_EndDialog()也释放对话框所占用的内存资源。

函数ISHELL_CreateDialog()并不返回它所创建的对话框结构指针。ISHELL_GetActiveDialog()用于取得堆栈顶的对话框Idialog指针。使用这个指针来调用Idialog提供的接口函数：IDIALOG_GetControl()用于取得对话框中任一控件指针。IDIALOG_SetFocus()用于指定具个多个控件的对话框中哪个控件获取焦点以接收用户输入。

AEE Shell同时也提供了创建简单常用对话框的函数：ISHELL_Prompt()。该函数显示一个带有Soft key控件的对话框，可以提示用户作出选择。当用户按下某个键时，消息EVT_COMMAND将发送给Applet，同时将终止提示框。此外还提供了两个显示只读信息的消息框函数：ISHELL_MessageBox()和ISHELL_MessageBoxText()。这两个函数不同之处在于一个使用资源文件，另一个直接指定提示的消息和标题。当用户控键盘之后，对话框则终止。

设备及应用程序配置信息

这些函数可以获得关于设备或是应用程序的相关配置信息。ISHELL_GetDeviceInfo()返回一个指向AEEDeviceInfo结构的指针，这个结构提供了关于设备屏幕大小、支持的颜色、可用内存大小，字符编码方式等。

ISHELL_GetPrefs() 和 ISHELL_SetPrefs()提供了应用程序注册配置信息的一般机制。ISHELL_SetPrefs()将Applet的ClassID、版本号与配置数据关联。其它的Applet可以通过指定ClassID、版本号调用ISHELL_GetPrefs() 来取得该配置数据。

通知

IShell的通知机制允许一个BREW类在某种事件发生时通知其它类。一个需要被激活以接收某个通知消息的类必需向AEE注册其需要响应的通知事件。

Shell指出了通知类的ClassID和通知消息事件号。当需要发送通知时，通知类调用ISHELL_Notify()向那些注册过需要接收该通知的类发送通知。

AEE Shell提供了两种方法用于一个类注册需要响应的通知事件。

通过在MIF文件中指定Applet需要响应的通知事件。该方法用于应用必需响应某个事件即使它没有运行。一个例子是，来去电记录应用。在打电话或是收到来电时都必需得到通知，即使用户当前没有运行这个软件。

如果一个应用只要需要时响应某个通知事件。调用ISHELL_RegisterNotify()来初始化事件通知。例如，一个游戏软件在运行过程中，如果收到来电，将提示用户是否接电话还是继续玩游戏。这个游戏程序只在运行才需要响应来电通知事件。

资源文件和文件处理器

AEE Shell提供了一组函数以帮助应用从文件中读取各种类型的数据，这些文件可以是由资源编辑器生成的资源文件 (.bar) 或某种MIME文件或是某种含有特定扩展名的文件。开发者也可以通过自定义文件处理器来扩展BREW识别文件的能力以处理特定的MIME文件。

下面的函数用于读取资源文件中数据，每个函数的参数包括资源文件名和相应的资源号。

• ISHELL_LoadResData()从资源文件读取除字符串和图象以外的数据，当前支持是和对话框资源相关的数据，通过ISHELL_FreeResData()来释放这部分资源所占据的内存空间。
• ISHELL_LoadResImage()从指定的资源文件中读取位图，并返回一个指向IImage接口的指针。IIMAGE_Release()用于释放这部分内存。
• ISHELL_LoadResObject()用于完成调入声音和图像资源。ISHELL_LoadImage()、ISHELL_LoadResImage()、 ISHELL_LoadSound(),和ISHELL_LoadResSound() 都是基于这个函数的宏以调入不同类型的资源。
• ISHELL_LoadResSound()从指定文件中载入声音资源，并返回一个指向IsoundPlayer接口的指针。函数ISOUNDPLAYER_Release()用于释放这部分内存。
• ISHELL_LoadResString()从文件中读取字符串资源。

ISHELL_LoadImage() 和 ISHELL_LoadSound() 也支持从不是资源文件(.bar)中读取图像和声音。但这些文件必需是BREW支持的MIME格式文件。如Bmp文件、midi文件等。

使用ISHELL_RegisterHandler()来为一个MIME格式文件注册一个处理器类，将其与这个类的Class ID关联。ISHELL_GetHandler()返回处理某种MIME文件的处理类Class ID。

定时器

AEE Shell 定时器用于已经被初始化的应用中 (其引用值不为0) 在指定的时间执行某个动作。这个时间通常比较短(几秒或是几毫秒)。使用AEE Shell的告警机制来在比较长的时刻执行某个动作，即使该应用当前没有被初始化。

调用ISHELL_SetTimer()来启动一个定时器，指明延迟的时间以及回调函数和回调函数相应参数。当定时器到期时，AEE Shell将调用这个回调函数。BREW的定时器都是一次性，而非循环性的，因此指定一个定时器重复几次是不行的。但是可以再这个回调用函数中重新调用ISHELL_SetTimer()可以达到这个功能。

函数ISHELL_GetTimerExpiration()用于读取一个定时器到期还需要多长时间，一个定时器是由它的回调用函数和参数来确定的，ISHELL_CancelTimer()用于取消一个正在运行的定时器。如果参数提定为NULL，则该Applet所关联的所有定时器将都被取消。同样在应用退出时，定时器也将被取消。

IDisplay类

IDisplay类接口提供了取得显示设备尺寸、绘制矩形、绘制位图等功能函数。同时BREW还提供了一个IGraphics类以增强BREW图形功能。

特别注意的是在绘制完文件、或图片之后，需要调用IDISPLAY_Update()来刷新屏幕。

由IDisplay类提供的函数可以参见API手册。