BREW SDK入门篇（二）
第二部分 – 在模拟器上运行“Hello BREW”
在跟随本文学习相关知识点之前，你需要以下环境：
1． Microsoft Visual C++ 6.0®(或更高版本)
2． 1.1版的BREW SDK.
要了解系统最低要求，和获得更细节的资料，SDK的安装指导，请查看SDK 1.1的README文件。注意，在这里我假设你已经读过了本系列中之前的一篇文章，“什么是BREW”以及本系列的前一篇文章“第一部分－预备知识”。我进一步假设你已经创建了一个模块信息文件（helloBREW.mif）和一个BREWx小程序资源文件（helloBREW.bar）并且分别将他们拷贝到了“...yourBREWdir\Examples\mif\256Color\”和“...yourBREWdir\Examples\en\256Color\”两个目录。同时，在“...yourBREWdir\Examples\helloBREW\”目录必须有用BREW资源编辑器生成的helloBREW_res.h文件，用BREW应用程序向导创建的应用程序源文件（helloBREW.c）。如果你需要了解更多，可以阅读上面提到的第一部分，或者阅读SDK附带的文档。
在这个例程中，你需要知道文件名是非常重要的。特别的，应用程序目录和模块信息文件（.mif）必须目标.dll文件名字相同（也就是前缀相同）。注意，你可以通过打开项目设置对话框（选择项目菜单>设置）的Link选项卡来定义.dll文件的名字。如果你按照第一部分的去做了，应该在相应目录已经有了正确命名的文件。
最后，提醒一下，在本文中“小程序”和“应用程序”这两个词会交替使用，都代表同一事物。
设置Visual C++
图1
在第一部分，所有的必须项目设置都是由BREW应用程序向导来管理。但我们仍然需要提供一个可执行文件以便在调试阶段运行.dll文件，同时还要确保BREW能够找到应用程序的.dll文件。为了满足第一个要求，我们需要为BREW_Emulator.exe提供路径，如图1所示。
为了满足第二个要求，我们要确保链接程序将helloBREW.dll写在项目的根目录里（...\helloBREW\），而不是默认的debug目录（...\helloBREW\debug\）。因为模拟器自动在名为helloBREW的目录里寻找helloBREW.dll。图2显示了Visual C++项目设置对话框里的Link选项卡应该输入的输出文件名称。
图2
理解源代码
首先我们来大致了解一下应用程序向导在helloBREW项目中生成的源代码。如果你还没有这么作过，请用Visual C＋＋打开helloBREW项目，然后选择FileView并展开Source Files文件夹。你可以看到3个源代码文件：AEEAppGen.c，AEEModGen.c，以及 helloBREW.c。前两个文件使得我们的应用程序能够绑定到BREW的应用程序执行环境（AEE）。AEEModGen.c管理模块，每个模块（module）基本上包括1个以上互相依赖的小程序(applets)。当一个终端用户激活了一个应用程序，AEE创建模块，由这个模块调用每个应用程序必须提供的AEEClsCreateInstance()函数，依次实例化应用程序。
这让我们开始了解小程序（applet）和应用程序（application）可以（比较宽松）地互换使用的原因。为什么呢？因为小程序可以理解为一个容器，他容纳了仅允许开发人员创建的功能与AEE交互并且在设备上运行的所有文件。举例来说，这样一个容器可以提供对shell服务的接口和对设备显示器的接口。这样我们可以认为一个应用程序是一个小程序加上开发任何创建的功能。实际上，如果在这个例子里我们用C++原理来说明，helloBREW（开发人员创建的功能）要public地从BREW的AEEApplet结构继承，从这个角度看，一个应用程序就是一个小程序（is a的关系）。AEEAppGen.c提供AEEApplet_New()函数，helloBREW将调用这个函数来设置helloBREW应用程序的AEEApplet部分。很快我们会更详细地讨论AEEClsCreateInstance()和AEEApplet_New()。
图3
现在我们对这些部分如何相互结合有了个基本的概念，现在让我们看看BREW应用程序向导生成的框架代码。图3显示了这个源代码，只有最基本的部分。至于所include的头文件，你可能都已经猜到了，AEEModGen.包含了AEEModGen.c的声明，AEEAppGen.h同样声明了AEEAppGen.c。AEEShell.h提供了shell接口API的声明。如果你希望更多的了解这个重要的接口，可以在BREW SDK附带的BREW API参考里查找IShell。这里我们将不作深入研究，将我们自己的代码加到helloBREW.c中。
现在，我们跳过helloBREW_HandleEvent()的定义来看AEEClassCreateInstance() （也可能是AEEClsCreateInstance()，译者注）。这个函数是helloBREW接触到AEE的地方。当AEE向应用程序传递一个启动的请求，AEEModGen.c中定义的AEEModCreateInstance()就调用小程序（applet）型的AEEClassCreateInstance()函数。因为BREW是单线程的，所以，不论一个模块里有多少个小程序，同一时间只有一个小程序被激活。通过调用ISHELL_StartApplet()，一个小程序可以被另一个小程序启动。在这种情况下，当前的小程序被暂停，转而用ISHELL_StartApplet()提供的class ID调用AEEClassCreateInstance（）。显而易见，AEEClassCreateInstance()需要模块里每一个class ID的逻辑分支。在我们的模块里只有一个小程序，因此AEEClassCreateInstance（）只需要处理一个class ID。
在前面的文章里，我们记得在helloBREW.mif文件里生成了一个helloBREW的class ID。MIF编辑器创建了一个helloBREW.bid文件，其中用#define将这个class ID定义为：AEECLSID_HELLOBREW。很明显的，这个模块从模块信息文件（helloBREW.mif）文件中获得了class ID，并且将其作为第一个参数传递给了AEEClsCreateInstance（）。
第二个参数，pIShell，是一个IShell指针，是在模块第一次加载的时候由AEE提供的。在调用AEEApplet_New()的时候，AEEApplet结构的m_pIShell成员必须被设置成pIShell。这个IShell指针提供了helloBREW对IShell接口所有API的访问。
第三个参数，po，是一个指向包含了helloBREW模块的指针，这个参数将在调用AEEApplet_New()时对AEEApplet结构的m_pIModule参数进行初始化。我们的代码不会涉及到这个指针。AEEAppGen.c中定义的AEEAppletRelease()函数需要这个指针在结束helloBREW时释放动态分配的模块。
最后，ppObj是指向普通指针的指针。这里用一个void类型的**，因为*ppObj可以指向两种东西。幸运的是，我们只需要关系IApplet类型的对象。要是你对指针的用法有点生疏，必须使用双间接寻址，以保证当AEEApplet_New()返回时*ppObj指向一个有效的IApplet对象。如果ppObj简单地定义为 void *ppObj（即单一的间接寻址），ppObj在AEEApplet_New()返回时就不会有所改变。C语言的参数传递机制将仅向AEEApplet_New()传递ppObj指针的一个简单拷贝，而不改变在AEEClsCreateInstance()中原有的值。由于我们想让AEEApplet_New()修改在AEEClsCreateInstance()中引用的同一指针，我们只能传递值参，而不是形参。
传递给AEEApplet_New()函数的倒数第二个参数是一个指向我们应用程序事件句柄的指针。当AEE一旦收到去往helloBREW的事件，都会调用这个函数。如果最后一个参数是非空的，我们就需要传递指针给一个在应用程序终止时释放动态分配数据的函数。这个PFNFREEAPPDATA是一个函数指针，这个函数接收IApplet *类型的参数，返回void。为了演示，我们将在helloBREW里加入这样的一个函数。
我们看helloBREW_HandleEvent()框架化的代码。第一个参数指向IApplet实例。在这个函数里，pi将被用于访问小程序的m_pIShell和m_pIDisplay数据成员。当我们向helloBREW添加自己的代码时，我们会更加详细地讨论这一点。
第二个参数，eCode，就像它的名字一样，指的是用于发现是什么动作导致对helloBREW_HandleEvent()调用的事件代码。最后两个参数包括了事件型的数据。在头文件AEE.h中可以找到完整、详尽的事件列表，还有对通过事件型参数wParam和dwParam提供的数据的描述。在BREW的SDK用户指南里可以找到更易读更友好的事件列表，包括不同的按键事件和按键代码以及对wParam和dwParam事件型内容的说明。
添加源代码
现在让我们在helloBREW中加入我们自己的代码。你可以在“...yourBREWdir\Examples\HelloWorld\”下的helloworld.c中看到一个简单版本的“hello”。为了防止重复并且让我们的例子更加有趣，我们将创建自己的小程序数据结构，提供InitAppData()和FreeAppData()函数，从资源文件（helloBREW.bar参考第一部分预备知识）中加载字符串并且用BREW的IStatic控制器显示他们。
正如上图4显示的，我们需要在include的头文件列表中增加AEEStdLib.h。这个头文件包括了MALLOC() 和FREE()，以及在BREW API参考中提到的helper函数。
然后，我们的应用程序需要能够访问helloBREW.bid中的class ID和helloBREW_rew.h中的字符串ID。
最后，图4显示了几个常数的定义；1个定义缓冲大小，一个定义屏幕边缘与静态控制器边界之间的象素数量。
图5
图5从定义我们的小程序数据结构开始。注意，非常重要的一点是，一个应用程序里不能有任何静态（全局）数据。因而我们的应用程序数据结构就定义为全局的数据结构（struct，至少C程序是这样）。并且我们让AEEClsCreateInstance()来管理堆里的实例。这又带来另一个非常重要的注意点：设备上的堆栈空间是非常有限的。举例来说，Kyocera QCP3035e仅有500字节的可用堆栈空间。很明显的，你需要尽量少的使用堆栈，为了达到这个目的，你可以将函数调用的层次降到最少，尽量将非原子化（可分割的，译者注）本地变量分配至堆，并且当需要传递的数据大于4位时，即使用指针。
应用程序数据结构提供了一个容器，用于装载在整个应用的生命周期中程序员需要维护的所有东西。这包括应用程序的AEEApplet部分，在这里可以访问shell，显示，和维护模块指针。AEEApplet必须为这个数据结构的第一个成员，这是强制性的。这个数据结构另外一个成员是一个指向用于显示我们定义的字符串的IStatic控制器的指针。
图6
图6显示经过我们修改后的AEEClassCreateInstance()函数。首先也是最重要的，我们修改了传入AEEAppletNew()的第一个参数。除了helloBREW的AEEApplet部分所需要的空间外，我们还需要用AEEApplet_New()来为小程序数据结构的IStatic *分配空间。为实现这一点，我们将sizeof(hb_app)传递给AEEApplet_New()作为第一个参数，而不是原来的sizeof(AEEApplet)。
第二步，为了在helloBREW中增加一个FreeAppData()函数，我们需要向AEEApplet_New()传递一个指针(hb_FreeAppData())作为最后一个参数。这个函数将被登记入AEE并且在应用程序终止时自动调用。图9显示了hb_FreeAppData()的定义。就像你看到的，这个函数的基本任务就是调用ISTATIC_Release()来释放IStatic控制器。
AEEClsCreateInstance()最后改变就是调用hb_InitAppData()，在这里，我们的小程序数据结构中的IStatic *成员被初始化为NULL，如图9所示。
图7
如图7所示，helloBREWHandleEvent()中对BREW应用程序向导生成的初始代码有大量修改。在最上面，我们定义了一个指向我们的小程序数据结构的指针，并且将本函数的第一个参数，IApplet *分配给这个指针。整个事件句柄中，这个指针被用于访问helloBREW中AEEApplet部分的m_pIShell成员，此外还提供对我们用来代表IStatic控制器的m_pIStat指针的访问。
在EVT_APP_START的开头，我们定义的第一个本地变量是AEEDeviceInfo类型变量。这个结构包括了保存设备屏幕尺寸和颜色深度的成员变量。更详细的数据成员介绍可以在BREW API参考最后的数据结构（数据类型，译者注）章节中找到。记得我提醒过关于尽量减少堆栈空间的使用，我们应该在堆上为这个结构分配内存，并且在本地定义指针来监视它。由于这个小程序不需要担心堆栈空间耗尽的危险，为了简单的缘故，我将这个结构定义为本地变量。
接下来，我们看到一个简单的矩形对象（AEERect），我们用来确定静态控制器的大小和位置，并且确定几个缓存分别保存m_pIStat的标题和文本。AECHAR是uint16的类型定义(typedef)（参考AEE.h），而uint16又是无符号短整数的类型定义（参考AEEComdef.h）。这样AECHAR可被用来存放Unicode或者成为宽字符集（wide characters）类型变量。这样wbufTtl和wbufTxt指向的是由宽字符集中的字符组成的以空结尾的字符串。参考BREW API参考中的Helper函数章节，了解操纵宽字符集字符串的工具。
在验证完m_pIShell的有效性后，我们可以调用来给di赋值。接下来，屏幕的尺寸成员di.cxScreen和di.cyScreen被用于设置装有静态控制器的位置、尺寸的矩形对象。在屏幕坐标系统中，原点是显示器的左上角，而当我们向右移时x坐标增大，向下移时y坐标增大。
在调用ISHELL_CreateInstance()时指定AEECLSID_STATIC为请求接口的class ID。假设成功，这个函数调用返回时m_pIStat将指向一个有效的IStatic。其它接口的class ID可以在aeeclassids.h中找到。在创建了IStatic后，我们调用ISTATIC_SetRect()来设置它的矩形，将指向刚才初始化的矩形结构的指针传递给他。
在为之前定义的缓冲区（wbufTtl，wbufTxt）分配了内存后，我们调用ISHELL_LoadResString()两次：一次是为IStatic的标题，一次是文本。这两个缓冲区则将标题和文本提交给ISTATIC_SetText()。ISTATIC_SetProperties()用于定义标题和文本的位置，并且调用ISTATIC_Redraw()在屏幕上显示静态控制器。参考BREW API参考中的IStatic章节可以了解更多关于这些函数的调用方法。
注意BREW不能容忍内存泄漏。因此你需要确信所有对MALLOC()的调用都相对应的有对FREE()的调用，而对ISHELL_CreateInstance()的调用相对应的有对I*_Release()的调用。在EVT_APP_START的最下面释放(FREE())了使用到的两个缓冲（buffer）。HelloBREW在hb_FreeAppData()中调用Istatic_Release()时释放Istatic实例。
图8
图8显示helloBREWHandleEvent()的剩余部分。这里我们增加了一个EVT_KEY事件，用于应用手机上“CLR”按键的标准。当“CLR”按钮按下时，我们通过返回FALSE来通知AEE应该关闭应用程序了。在手机上“CLR”按键预置的意思为“退回上一级”，你的应用程序应该实现这个动作。
因为释放m_pIStat的事情交由hb_FreeAppData()处理，因此我们在EVT_APP_STOP事件句柄中不需要做任何事情。
图9
运行helloBREW
图10
现在来启动BREW模拟器（Emulator），可以通过点击BREW SDK程序组中的快捷方式，也可以点击Visual C++里画有红色惊叹号的按钮来启动模拟器。
点击BREW SDK程序组中的快捷方式，或者点击Visual C++中的红色惊叹号来启动BREW模拟器。用左右方向键在BREW应用程序管理器中定位helloBREW，选中后，你可以看到在模拟器屏幕的正中显示了我们所作的85×40的大图。在键盘上按回车，模拟器的显示器上将显示如图10中第二帧的图像。
由于我为helloBREW.mif另外定义了一个MIF的目录，所以你的模拟器显示的第一帧可能不会象上图10中显示的一样。我这么做的目的是避免在一大堆SDK中自带的实例应用的图标中去找helloBREW的图标。也就是说，模拟器只显示在当前指定的MIF目录中有有效.mif文件的应用程序。你可以将生成的helloBREW.mif移到，例如，“..yourBREWdir\Examples\yourmif\256Color\”中，然后在模拟器的工具菜单中将它设置为初始的mif目录。详细的设置指导可以参考BREW MIF编辑器指南。
用模拟器调试
如果您按照本文开始部分的指导来设置Visual C++的部分，你可以象平常一样使用Visual C++调试器。例如，为了确信AEEClsCreateInstance()象所期望的那样工作，你可以将光标置于这个函数中，并点击调试工具条中的“Run to Curor”。然后你可以单步运行这个函数，设置监视某些变量的值，跳入其它函数，或者将光标置于其它函数或者事件句柄并且再次点击“Run to Curor”。如果你对Visual C++调试器不熟悉，你应该阅读Visual C++自带文档的相关章节。
如果模拟器在启动的时候不能显示Sharp Z800的话机界面，你可以利用File> Load Device...来更换所模拟的设备。在“...yourBREWdir\devices\”中选择Z800话机设备文件，以qsc结尾的，并点击打开以加载该设备。
最后需要注意的是2.0SDK中所带的模拟器结合了更为严格的堆检验，这将帮助你找到内存溢出，数组越界等在早期开发过程中可能出现的错误。2.0的模拟器可以与1.x的SDK联合使用。关于如何在一台机器上安装多个版本的SDK等信息可以参考SDK2.0的安装指导。
© Copyright 2002, Golden Creek Software Inc.
图7
如图7所示，helloBREWHandleEvent()中对BREW应用程序向导生成的初始代码有大量修改。在最上面，我们定义了一个指向我们的小程序数据结构的指针，并且将本函数的第一个参数，IApplet *分配给这个指针。整个事件句柄中，这个指针被用于访问helloBREW中AEEApplet部分的m_pIShell成员，此外还提供对我们用来代表IStatic控制器的m_pIStat指针的访问。
在EVT_APP_START的开头，我们定义的第一个本地变量是AEEDeviceInfo类型变量。这个结构包括了保存设备屏幕尺寸和颜色深度的成员变量。更详细的数据成员介绍可以在BREW API参考最后的数据结构（数据类型，译者注）章节中找到。记得我提醒过关于尽量减少堆栈空间的使用，我们应该在堆上为这个结构分配内存，并且在本地定义指针来监视它。由于这个小程序不需要担心堆栈空间耗尽的危险，为了简单的缘故，我将这个结构定义为本地变量。
接下来，我们看到一个简单的矩形对象（AEERect），我们用来确定静态控制器的大小和位置，并且确定几个缓存分别保存m_pIStat的标题和文本。AECHAR是uint16的类型定义(typedef)（参考AEE.h），而uint16又是无符号短整数的类型定义（参考AEEComdef.h）。这样AECHAR可被用来存放Unicode或者成为宽字符集（wide characters）类型变量。这样wbufTtl和wbufTxt指向的是由宽字符集中的字符组成的以空结尾的字符串。参考BREW API参考中的Helper函数章节，了解操纵宽字符集字符串的工具。
在验证完m_pIShell的有效性后，我们可以调用来给di赋值。接下来，屏幕的尺寸成员di.cxScreen和di.cyScreen被用于设置装有静态控制器的位置、尺寸的矩形对象。在屏幕坐标系统中，原点是显示器的左上角，而当我们向右移时x坐标增大，向下移时y坐标增大。
在调用ISHELL_CreateInstance()时指定AEECLSID_STATIC为请求接口的class ID。假设成功，这个函数调用返回时m_pIStat将指向一个有效的IStatic。其它接口的class ID可以在aeeclassids.h中找到。在创建了IStatic后，我们调用ISTATIC_SetRect()来设置它的矩形，将指向刚才初始化的矩形结构的指针传递给他。
在为之前定义的缓冲区（wbufTtl，wbufTxt）分配了内存后，我们调用ISHELL_LoadResString()两次：一次是为IStatic的标题，一次是文本。这两个缓冲区则将标题和文本提交给ISTATIC_SetText()。ISTATIC_SetProperties()用于定义标题和文本的位置，并且调用ISTATIC_Redraw()在屏幕上显示静态控制器。参考BREW API参考中的IStatic章节可以了解更多关于这些函数的调用方法。
注意BREW不能容忍内存泄漏。因此你需要确信所有对MALLOC()的调用都相对应的有对FREE()的调用，而对ISHELL_CreateInstance()的调用相对应的有对I*_Release()的调用。在EVT_APP_START的最下面释放(FREE())了使用到的两个缓冲（buffer）。HelloBREW在hb_FreeAppData()中调用Istatic_Release()时释放Istatic实例。
图8
图8显示helloBREWHandleEvent()的剩余部分。这里我们增加了一个EVT_KEY事件，用于应用手机上“CLR”按键的标准。当“CLR”按钮按下时，我们通过返回FALSE来通知AEE应该关闭应用程序了。在手机上“CLR”按键预置的意思为“退回上一级”，你的应用程序应该实现这个动作。
因为释放m_pIStat的事情交由hb_FreeAppData()处理，因此我们在EVT_APP_STOP事件句柄中不需要做任何事情。
图9