BREW Applet框架

BREW Applet框架

The Framework of BREW Applet

 

田海立

2006-5-6

 

摘要

本文首先通过一个简单的Applet介绍BREW环境下Applet的运行环境，然后分析如何在一个Module中实现多个Applet的方法，以及BREW中分布在不同的Module中的各个Applet之间的启动交互关系。

 

 

摘要... 1
1 BREW概览... 2
  1.1 BREW简介... 2
  1.2 BREW中的几个基本概念... 2
  1.3 BREW模拟开发环境... 3
2 麻雀虽小，五脏俱全之HelloBREW.. 3
  2.1 文件组成... 3
  2.2 Module和Applet的总体框架... 4
  2.3 实现HelloBREW.. 6
    2.3.1 类型定义... 6
    2.3.2 AEEClsCreateInstance()的实现... 6
    2.3.3 HandleEvent()的实现... 7
    2.3.4 加入事件处理代码... 8
  2.4 HelloBREW的执行结果... 9
3 多个Applet实现在同一个Module里... 9
  3.1 文件组成... 9
  3.2 实现AppsInOneModule. 11
    3.2.1 类型定义... 11
    3.2.2 AEEClsCreateInstance() 函数的实现... 11
    3.2.3 Applet构造函数的实现... 12
    3.2.4 Applet事件处理... 12
  3.3 执行序列... 13
4 Applet实现在不同的Module里... 14
总结... 16
参考资料及进一步参考... 16
关于作者... 17

 

 

1 BREW概览

1.1 BREW简介

BREW（Binary Runtime Environment for Wireless，即无线二进制运行环境）是QUALCOMM 公司的产品。它以组件（COM）的组织形式封装了底层平台提供给应用开发的服务，屏蔽了底层的实现细节，而提供给应用层统一的API。它所提供的API描述的是Spec而非实现细节，不管今后QUALCOMM的平台技术如何发展，其实现的功能和实现该功能的API规范应该是确定并向后兼容的。

BREW上接受的OEM或其他第三方软件厂商提供的最终软件实体是Module的执行体——Win32模拟环境下是 *.dll，真实机器上是 *.mod，这也体现了BREW中的Binary。另外，也可以在BREW运行时从网络上下载BREW所接受的实体，加入到BREW中来运行。

1.2 BREW中的几个基本概念

BREW中的有Applet和Extension，Applet是一个独立运行（从应用开发角度看）的实体，有Applet Context，简记为ACONTEXT；Extension通过实现它所定义的接口提供服务给Applet或其它Extension，Extension不是独立的运行实体，它运行在调用它的Applet（直接或间接地，当前Extension Ext1的某个服务Ext1::srv可能不是由Applet直接调用，但是调用Ext1::srv的Extension Ext2归根到底还是可以追溯到某个Applet）的ACONTEXT中。Applet和Extension都是被包含在Module里面的，它们之间的关系如图一所示。

 

 

图一、BREW中几个概念之间的关系

 

       BREW最终接受的是Module，所以你所提供的Applet和Extension必须在某个Module中；另一方面，一个Module里可以有0…n个Applet或Extension，也可以同时有Applet和Extension，还可以两者都没有，不过两者都没有的Module也没有实际意义。Module的属性和它所包含的Applet和Extension的信息，以及Dependency关系都描述在MIF（Module Information File）文件里，BREW通过该描述文件检索它所需要的信息，并通过相应的Module二进制文件完成相应的操作。

       BREW加载Applet或Extension时，首先检查包含它的Module是否已经被加载到内存里，如果还没在内存里，BREW要做的工作是先把该Module加载；接着BREW通过该Module的IMODULE_CreateInstance() 来创建Applet或Extension的一个实例，然后才完成Applet或Extension的真正加载。

1.3 BREW模拟开发环境

本文所描述的BREW环境和概念都是基于BREW 3.0.1 ，采用的程序在下面软件环境中调试通过：

BREW SDK 3.0.1 ，包含
              API手册
              BREW Simulator, MIF Editor, etc.
              Header files & some src files

Microsoft Visual studio，包含
              Visual studio 6.0
              Visual studio 6.0 Service Package 5

       Additions
              BREW Application Wizard
              BREW Addins for vs60

2 麻雀虽小，五脏俱全之HelloBREW

有了上面BREW的概念以及开发调试所需的软件环境，下面我们看一个简单的BREW Applet——HelloBREW。

2.1 文件组成

       在ms vs60环境中通过BREW Application Wizard创建一个HelloBREW 工程。自动生成和关联的文件如图二所示。

 

 

图二、HelloBREW中自动生成的文件

 

       AEEAppGen.c和AEEModGen.c是BREW SDK中自代的文件，分别是IApplet和IModule的一个实现。HelloBREW.c是新生成的文件，利用了AEEApplet这一Applet实现模版来实现特定的Applet。

这些文件将连同BREW SDK提供库一块被编译并连接成一个dll文件——HelloBREW.dll（WIN32环境中，Module的执行体）。但是，只是有这些还不行，还没有跟BREW的Module及Applet关联起来，BREW Simulator也不会知道如何创建和加载它们。我们还必须创建一个MIF文件来描述这些信息。

       假定，我们创建的HelloBREW这个Applet包含在HelloBREW Module中。那么，我们用BREW MIF Editor创建一个HelloBREW.mif文件；然后在其中创建一个Applet HelloBREW，并把这个Applet的AEECLSID描述文件HelloBREW.bid保存；最后通过菜单Build| Compile MIF Script来编译这个MIF脚本，保存退出。用BREW MIF Editor创建HelloBREW.mif的过程如图三所示。

 

 

图三、编辑HelloBREW.MIF

 

       上面工作做完之后，vs60的工程就可被Build成一个BREW的Module执行体，并可用BREW Simulator来装载执行。但是，现在这个Module的Applet什么工作也没做，执行起来也没什么意义，笔者打算在分析Applet框架并加入一些处理代码之后，再来执行之。

2.2 Module和Applet的总体框架

通过调试跟踪上述的HelloBREW 工程，得出图四所示的BREW的 Module和Applet的执行序列。

 

 

图四、BREW中Module和Applet演示——HelloBREW

 

AEEModGen、AEEAppGen和HelloBREW 一起被编译并连接为 HelloBREW.dll。如1.2节所述，BREW 刚启动时并不是加载所有的 Module，只有在 Module 所包含的 Applet 或 Extension 需要被加载时，BREW才加载该Module。所以，当用户点击执行HelloBREW 这个 Applet 时，BREW 通过调用 AEEMod_Load() 首先来加载这个 Module [序列1]；AEEModGen 通过 AEEStaticMod_New() 完成 IModule 创建和初始化的工作之后，Module的加载过程完成[序列2&3]。

Module被加载完成之后，BREW就通过 IMODULE_CreateInstance() 来创建Applet，AEEModGen通过HelloBREW的AEEClsCreateInstance()，把Applet的具体创建工作交给HelloBREW [序列4, 5 & 6]；而AEEAppGen通过AEEApplet_New() 提供了IApplet创建和初始化的便利，HelloBREW通过在AEEClsCreateInstance()中调用此函数，把具体的事件处理函数HelloBREW_HandleEvent() 和程序退出时的清理函数注册到BREW里。当完成上述工作并返回AEE_SUCCESS之后， Applet的创建也就完成了 [序列 4~8]。

如果Applet是因为要运行而被创建并成功创建之后，会马上收到一条EVT_APP_START的事件，此时你的Applet已经正常的加载运行了，并通过HandleEvent函数来处理它所收到的各种事件。

 

再把上述过程总结一下，AEEAppGen和AEEModGen其实并不是独立的实体对象，只是由于它们是BREW SDK提供的，为了明确展现开发BREW Applet时，程序员自己所要做的工作的需要，才把它们单独列出来。要看程序员所需要做的工作，只需要从图四中HelloBREW的生命线（竖线）看过去，也就是只要实现AEEClsCreateInstance()，另外，HelloBREW调用AEEApplet_New() 时，把注册自己实现的事件处理函数和程序退出时的清理函数，而退出时的清理函数也可以不定义，所以最后，程序员所要实现的函数只有AEEClsCreateInstance()和事件处理函数。

2.3 实现HelloBREW

2.3.1 类型定义

首先，定义一个结构体，里面可以存放用户关心的数据。

 

typedef struct _HelloBREW {
    AEEApplet       a;              // Must be AEEApplet
    AEEDeviceInfo  DeviceInfo;    // access to the HW device info
    IDisplay       *pIDisplay;    // access the Display interface
    IShell         *pIShell;      // access the Shell interface
} HelloBREW;

代码片断一、HelloBREW类型的定义

 

2.3.2 A EEClsCreateInstance()的实现

 

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

    if (ClsId == AEECLSID_HELLOBREW)
    {
        // Create the applet and make room for the applet structure
        if (AEEApplet_New(sizeof(HelloBREW),
                          ClsId,
                          pIShell,
                          po,
                          (IApplet**)ppObj,
                          (AEEHANDLER)HelloBREW_HandleEvent,
                          (PFNFREEAPPDATA)HelloBREW_FreeAppData))
        {
            if (HelloBREW_InitAppData((HelloBREW*)*ppObj))
            {
                // Data initialized successfully
                return (AEE_SUCCESS);
            }
            else
            {
                IAPPLET_Release((IApplet*)*ppObj);
                return EFAILED;
            }
        } // end AEEApplet_New
    }

    return (EFAILED);
}

代码片断二、HelloBREW 中 AEEClsCreateInstance() 的实现

 

这里定义了一个局部的初始化函数HelloBREW_InitAppData()，用来执行用户数据的初始化，比如，把初始化HelloBREW的下列成员DeviceInfo : AEEDeviceInfo; *pIDisplay: IDisplay; *pIShell: IShell。

 

2.3.3 HandleEvent()的实现

最后看，HelloBREW的主体——事件处理函数HelloBREW_HandleEvent()

原型为：

boolean HelloBREW_HandleEvent(HelloBREW* pMe, AEEEvent eCode, uint16 wParam, uint32 dwParam)

该函数通过eCode参数来决定消息的类型，然后做出相应的处理，所以它的主体是一个大的switch语句：

 

    switch (eCode)
    {
        // App is told it is starting up
        case EVT_APP_START:
            return (TRUE);

        // App is told it is exiting
        case EVT_APP_STOP:
            return (TRUE);

        // App is being suspended
        case EVT_APP_SUSPEND:
            return (TRUE);

        // App is being resumed
        case EVT_APP_RESUME:
            return (TRUE);

        case EVT_APP_MESSAGE:
            return (TRUE);

        case EVT_KEY:
            return (TRUE);

        // If nothing fits up to this point then we'll just break out
        default:
            break;
   }

   return FALSE;

代码片断三、HelloBREW 中事件处理的主体实现

 

如果事件被处理，该函数返回TRUE，否则返回FALSE。

 

2.3.4 加入事件处理代码

为了简单起见，笔者就直接在HelloBREW刚被加载也就是在收到EVT_APP_START事件的时候加入一些处理。对这个事件的处理也只是显示“Hello BREW”。相应的代码如下：

 

    AECHAR szText[] = L"Hello BREW";

    switch (eCode)
    {
        // App is told it is starting up
        case EVT_APP_START:
            IDISPLAY_DrawText(pMe->pIDisplay,    // Display instance
                              AEE_FONT_BOLD,       // Use BOLD font
                              szText,              // Text
                              -1,                  // -1 = Use full string length
                              0,                   // Ignored - IDF_ALIGN_CENTER
                              0,                   // Ignored - IDF_ALIGN_MIDDLE
                              NULL,                // No clipping
                              IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE);

            IDISPLAY_Update(pMe->pIDisplay);

            return (TRUE);

代码片断四、HelloBREW 中EVT_APP_START事件的处理

 

2.4 HelloBREW的执行结果

Build上面的HelloBREW 工程，生成HelloBREW.dll，然后用BREW Simulator执行之，得到的结果如图五所示。

 

 

图五、HelloBREW在模拟环境中的执行结果

 

3 多个Applet实现在同一个Module里

一个Module里可以有多个Applet，那么如何实现呢？

由图四知，BREW装载Module里的Applet时，都会通过AEEClsCreateInstance() 函数，完成Applet的创建，我们可以在这个函数里面做些处理，根据不同的AEECLSID，来创建不同的Applet。

3.1 文件组成

在ms vs60环境中通过BREW Application Wizard创建一个AppsInOneModule 工程，

并把工程的文件组织成图六所示。

 

 

图六、AppsInOneModule工程中的文件

 

AppFactory.c文件中实现AEEClsCreateInstance() 函数，根据不同的AEECLSID，调用各自的构造函数来创建相应的Applet。

AppMgr.c，Applet1.c和Applet2.c分别是各个Applet的具体实现。它们的内容大致都相同，如同HelloBREW一样要实现事件处理函数，但是没有AEEClsCreateInstance() 函数，而是把它改成自身的构造函数AppXXX_Constructor()。

Types.h 因为这些Applet之间可能要相互访问一些数据，把它们的类型定义放在一个统一的头文件里。

 

这个Module中要实现三个Applet，所以要把这个Module的描述文件AppsInOneModule.mif编辑成下图所示。

 

 

图七、编辑AppsInOneModule.mif

 

3.2 实现AppsInOneModule

3.2.1 类型定义

这里只是为了演示如何在一个Module中创建多个Applet，并不定义复杂的类型，如同2.3.1里面类型HelloBREW的定义那样定义三个类型AppMgr，Applet1和Applet2。

3.2.2 A EEClsCreateInstance() 函数的实现

函数原型为：

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

函数实现的主体根据不同的AEECLSID，调用各个Applet的构造函数来创建相应的Applet。

 

    switch (ClsId)
    {
    case AEECLSID_APPMGR:
        return AppMgr_Constructor(sizeof(AppMgr),
                          ClsId,
                          pIShell,
                          po,
                          (IApplet**)ppObj);

    case AEECLSID_APPLET1:
        return Applet1_Constructor(sizeof(Applet1),
                          ClsId,
                          pIShell,
                          po,
                          (IApplet**)ppObj);

    case AEECLSID_APPLET2:
        return Applet2_Constructor(sizeof(Applet2),
                          ClsId,
                          pIShell,
                          po,
                          (IApplet**)ppObj);

    default:
        return EFAILED;
    }

    return (EFAILED);

代码片断五、AppFactory.c 中 AEEClsCreateInstance() 的实现

 

3.2.3 A pplet构造函数的实现

如同2.3.2中的AEEClsCreateInstance()函数那样，各个Applet的构造函数分别把各自的事件处理函数XXX_HandleEvent() 和程序退出时的清理函数注册到BREW里。

3.2.4 A pplet事件处理

AppMgr收到EVT_APP_START和EVT_APP_RESUME时，都通过AppMgr_DrawitsScreen()输出“AppMgr Speaking...”，向大家问好。

AppMgr在Active状态，也就是屏幕上显示“AppMgr Speaking...”情况下，点击左软键将启动Applet1；点击右软键将启动Applet2。实现如下：

 

    switch (eCode)
    {
        // App is told it is starting up
        case EVT_APP_START:
            AppMgr_DrawItsScreen(pMe);
            return (TRUE);

        case EVT_APP_RESUME:
            AppMgr_DrawItsScreen(pMe);
            return (TRUE);

        ...

        case EVT_KEY:
            switch (wParam)
            {
            case AVK_SOFT1:
                // To start Applet1
                ISHELL_StartApplet(pMe->pIShell, AEECLSID_APPLET1);
                break;

            case AVK_SOFT2:
                // To start Applet2
                ISHELL_StartApplet(pMe->pIShell, AEECLSID_APPLET2);
                break;
            ...
            }
            return (TRUE);

        ...

代码片断六、AppMgr对事件的处理

 

Applet1和Applet2在收到EVT_APP_START事件时，通过Applet?_DrawitsScreen()输出“Applet? Speaking...”，向大家问好。

Applet?在Active状态，也就是屏幕上显示“Applet? Speaking...”情况下，点击右软键将关闭自身。实现如下：

 

    switch (eCode)
    {
        // App is told it is starting up
        case EVT_APP_START:
            Applet1_DrawItsScreen(pMe);
            return (TRUE);

        case EVT_KEY:
            switch (wParam)
            {
            case AVK_SOFT2:
                // To stop itself
                ISHELL_CloseApplet(pMe->pIShell, FALSE);
                break;
            ...
            }
            return (TRUE);

        ...

代码片断七、Applet1对事件的处理

 

3.3 执行序列

一个Module中实现多个Applet的处理过程与图四的HelloBREW中的处理过程基本相同。不同之处在于，AEEClsCreateInstance()中根据clsId分别调用相应Applet的构造函数来完成Applet的创建和初始化，当然这也就意味着各个Applet把各自的事件处理函数注册到BREW里。当各个Applet有事件需要触发的时候，BREW会通过相应的事件处理函数来分发各个Applet的事件。

一个典型的执行过程如图八所示。

 

 

图八、一个Module中实现多个Applet的处理过程

 

启动AppMgr之前首先要装载它的Module[序列1]；
       装载完成之后，BREW才通过IMODULE_CreateInstance()来创建AppMgr，IMODULE_CreateInstance()通过调用AppFactory的AEEClsCreateInstance()来实现[序列2~7]。
       AppMgr创建并装载完成之后，会收到EVT_APP_START事件，AppMgr收到这个事件之后显示“AppMgr Speaking…”。[序列8 & 9]
       点击左软键，AppMgr通过ISHELL_StartApplet()来启动Applet1[序列10]；
       BREW给AppMgr一个Suspend事件，设置AppMgr的状态为Suspended[序列11 & 12]；
       上面的事件处理完成之后，BREW同样通过这个Module的IMODULE_CreateInstance()来创建Applet1[[序列13 & 14]]。
       接下来的处理过程同AppMgr创建时的过程。

 

4 Applet实现在不同的Module里

Applet当然可以实现在不同的Module里，BREW通过mif文件知道了哪个Applet实现在哪个Module里，这样一来，当要加载某个Applet Applet1时，BREW会首先加载Applet1的Module Mod1；Applet1执行过程中要启动另外一个Applet2，如果Applet2与Applet1在同一个Module Mod1里，当然也就是Mod1已经被加载，那么BREW就会如图八中那样直接通过 Mod1 的 IMODULE_CreateInstance() 创建并加载 Applet2。

而如果 Applet2 与 Applet1 不在同一个 Module 里，而在 Mod2 内，BREW就会首先加载 Mod2；然后通过 Mod2 的 IMODULE_CreateInstance() 创建并加载 Applet2。处理的过程如图九所示。

 

 

图九、两个Module中的Applet的启动顺序

 

要验证这种情况，不需要另外再新建工程了，有了前面的HelloBREW和AppsInOneModule就够了。

Applet HelloBREW在HelloBREW这个Module里；AppMgr、Applet1和Applet2在AppsInOneModule里面。这里只要用一下这两个Module以及HelloBREW和Applet1这两个Applet就行了，在Applet1的事件处理函数中，添加对左软键的处理，直接启动HelloBREW就行了。对比代码片断七，现在的代码（斜体部分为新加的代码）如下：

 

    switch (eCode)
    {
        // App is told it is starting up
        case EVT_APP_START:
            Applet1_DrawItsScreen(pMe);
            return (TRUE);

        case EVT_KEY:
            switch (wParam)
            {
            case AVK_SOFT1:
                // To Start HelloBREW, which is contained in another module
                ISHELL_StartApplet(pMe->pIShell, AEECLSID_HELLOBREW);
                break;

            case AVK_SOFT2:
                // To stop itself
                ISHELL_CloseApplet(pMe->pIShell, FALSE);
                break;
            ...
            }
            return (TRUE);

        ...

代码片断八、点击Applet1左软键启动HelloBREW

 

总结

如果要写有交互的几个Applet，可以在一个Module里实现它们，也可以把它们分散在几个Module里面。

但是如果在多个Module里实现，现在vs60 studio环境下的调试手段无法跨越几个工程（对应BREW的Module）跟踪调试，所以笔者推荐，在Applet还不稳定的调试阶段，先把它们放在同一个Module里调试，待有Applet的功能确定，接口明确，性能稳定之后，就把这样的Applet按照它们的逻辑性组织在各自的Module里，接下来用稳定的Applet来调试剩下的Applet，直到所有的Applet都按照逻辑性组织在各自的Module里。

 

参考资料及进一步参考

[1] QUALCOMM, BREW API Reference Manual, v 3.0.1

HelloBREW & AppsInOneModule Source Code

 

关于作者

田海立，硕士，国家系统分析师，中国系统分析员协会专业顾问。

您可以通过 haili.tian(at)csai.cn 或 tianhaili(at)nju.org.cn 与他联系，到 http://blog.csdn.net/thl789/ 看他最新的文章。

 

版权声明：

◇ 本文为作者原创作品，版权归作者所有。
◇ 为了学习和研究，可转载本文，但必须与原文的内容和格式保持一致，并给出原文的原始链接！
http://blog.csdn.net/thl789/archive/2006/05/08/712453.aspx