BREW 3.0 API 參考資料簡介

本文档为开发者提供了开发 BREW 设备平台应用程序所需的 Binary Runtime Environment for Wireless™ (BREW™) 函数和数据结构的信息。
在本参考资料中
《BREW API 参考资料》的余下部分包括以下内容：
BREW API 接口
按字母顺序列出 BREW 接口和函数。
助手函数
按字母顺序详列助手函数。
数据类型
按字母顺序详列 BREW 接口使用的数据结构。
每个函数的说明均提供了以下信息：
说明
函数用法的说明。
原型
一个调用结构的示例。
参数A
需要输入和返回的对象。
返回值
从函数调用返回的项目，包括多种类型、消息、值、结构和说明。
备注
帮助理解函数的用法、限制和边界的特殊说明和附加信息。
副作用
（仅在适当情况下）
使用函数调用时函数表现的任何异常行为。 除非存在副作用，否则不显示该标题。
版本
引入此函数的版本。
另请参阅
相关函数或数据结构的交叉参考。
A 注意： 仅当参数表包含混合类型时，参数列表才显示 [in]、[in/out] 和 [out]。 如果表中都是输入参数，将省略 [in]。
BREW 继承函数
每个继承函数均链接至其基类。 以下是继承函数条目的一个示例。
IBITMAP_AddRef()
此函数继承于 IBASE_AddRef()。
详细信息
BREW 应用程序开发者可以得到相关的联机信息和支持。 请访问 BREW 网站了解详细信息：www.qualcomm.com/brew/zh/developer。
请求 BREW 的新功能
如果您在使用 BREW SDK 的过程中对它的功能有任何意见和想法， 欢迎您按如下地址给我们发送电子邮件:brew-request@qualcomm.com。
新功能反应小组将认真考虑您的每一个意见，并通过电子邮件尽快地给予您答复。
BREW™ 程序设计概念
本部分讨论以下 BREW 程序设计概念。
转至主题
学习
BREW SDK 的组件
BREW SDK 中包括的组件。
组件如何交互
如何配合使用下载 BREW SDK 后得到的各种组件和工具。
BREW SDK 目录结构
BREW SDK 中文版的组织方式。
使用小程序和模块
在 BREW 中如何使用小程序和模块编译应用程序 DLL。 还包括一些关于创建小程序和实例，处理小程序事件的主题。
BREW 开发指导原则
如何避免常见错误和缩短测试、调试和修改 BREW 源代码的时间。
创建新的应用程序
创建新 BREW 应用程序的方法。 还包括一些关于使用应用程序向导、处理特定语言资源和使用浮点运算的主题。
访问外壳服务
如何利用 IShell、IBase、IModule 和 IApplet 接口使模块和小程序可以访问外部服务。
事件处理概念
如何处理事件，包括切换事件。
在 EFS 中访问文件或 API
与桌面文件系统（例如 Windows XP）相比，如何在设备的 EFS 上运行应用程序。
监测进入的 SMS 消息
BREW 电话层如何监测进入的 SMS 消息（如 DMA 设备的 IS-637 SMS 消息）。
管理短时计时器和设备睡眠
如何处理设备睡眠模式和短时计时器。
开发屏幕保护程序
如何在 BREW 中创建屏幕保护程序，包括将应用程序注册为屏幕保护程序的过程。
扩展 BREW API
如何使用 BREW API 扩展自定义 BREW API。
从第三方应用程序调用 MobileShop。
如何向您的应用程序添加 MobileShop URL。
文件系统名称空间和 ACL
在 BREW 中如何处理文件系统名称空间和 ACL。
BREW 安全模式
BREW 如何管理设备上有问题的应用程序。
内容安全
如何确保安全处理从因特网、SMS 消息和其它外部信息源接收的消息。
使用小程序和模块
BREW SDK 的每个应用程序模块均作为独立的 Windows DLL 开发。 每个模块可以包含一个或多个小程序，且必须包含一个与之关联的 MIF。 使用 BREW MIF 编辑器创建的 MIF 包含关于模块内容的信息，如支持的类、支持的小程序、小程序权限以及小程序的详细信息（如标题和图标）。 MIF 还包含每个模块类唯一的ClassID，并指定导出哪些类供其它模块使用。 有关创建新 MIF 的详细信息，请参阅MIF 编辑器概述。
模块可以读取 BREW 资源文件中的数据，为应用程序提供字符串、图像和对话框等资源。 将特定语言和特定设备的数据保存在资源文件中，可以实现创建应用于各国（地区）语言和各类设备的应用程序版本。 要开发小程序的资源，需要使用资源编辑器生成二进制资源文件和对应的资源头文件。 有关创建新资源文件的详细信息，请参阅资源编辑器概述。
要在Simulator(模拟器)和目标设备上编译和运行小程序，必须开发一个 BREW 小程序。 SDK 提供了构成应用程序基础的源文件和头文件。 SDK 还提供了一些可实现 DLL 特定功能的文件，用于生成应用程序和资源文件。 在 BREW 环境下，设备上的应用程序与Simulator上的应用程序使用相同格式的资源和二进制资源文件。
以下是编译应用程序 DLL 需要的组件列表：
BREW SDK 附带的 BREW AEE 头文件
BREW 助手源文件，用于创建简单的模块
小程序源文件和头文件
使用 MIF 编辑器创建的 MIF
使用资源编辑器创建的小程序资源和资源头文件（可选）
注意： Windows 和设备的应用程序源文件保持相同。 植入 Windows 的 DLL 二进制和设备的特定二进制中的源文件也相同。
BREW 开发指导原则
以下开发指导原则有助于避免发生常见的错误，并可将测试、调试和重写源代码所需的时间量降至最低。 该指导原则可识别以下问题：
导致从 Windows 移植到 ARM 环境时出现问题
导致目标设备上出现问题，但在 BREW Simulator中不一定能够检测到
常规有效操作
通过研究和执行这些指导原则，您可以将从 Windows 移植到 ARM 的时间总量降至最低，并使应用程序尽可能在移动设备上正常运行。
开发指导原则
说明
执行 NULL 指针检查。
在以下两种情况下需执行检查：
创建 BREW 接口实例时必须检查 NULL 指针。 如果指针有误，则该接口将无法使用。
检查 BREW 方法或已分配内存所传递和返回的所有指针，以确保它们的有效性。 无效指针应使用异常处理机制进行处理。
避免堆栈溢出。
不要将大数组放在堆栈上。 不要在函数内将大数组或变量声明为本地变量，因为 BREW 环境可用的堆栈大小十分有限。 如果需要大量内存（例如，大于 256 字节），则使用动态内存分配操作符，例如 MALLOC 或 IHeap。
如果分配处于递归例程中，则动态分配缓冲区。 如果调用堆栈中的函数较深，则监控之前大堆栈缓冲区的堆栈。
不要编写紧凑循环。
使用紧凑循环会导致目标设备自动重置。 因此，不要编写需要花费大量时间处理应用程序中单个事件的紧凑循环。 这样可以防止将其它事件传递给应用程序，从而避免设备重置。
收到事件时，应用程序将进行所需处理，然后从该事件返回， 使得其它事件可以发送到该应用程序。
力求应用程序与设备无关。
要确保应用程序独立于内存大小、键盘、屏幕大小和色深而能够在任何目标设备上执行，请使用 ISHELL_GetDeviceInfo() 从目标设备获取说明。 使用该结果指定显示、按键和多媒体等参数， 而不要硬编码这些参数。
在不同设备上使用 CONVERTBMP 例程处理图像。
使用资源。
使用资源存储特定语言的字符串、对话框和位图。 这有助于本地化应用程序，将它从一种语言的目标设备移至另一种语言的目标设备。 不要在源文件中硬编码这些类型的信息。
清除内存。
由于目标移动设备上的可用内存十分有限，因此必须释放未使用的内存。 在以下两种情况下需释放内存：
必须释放所创建对象的所有实例。
应用程序终止时，必须释放所有动态内存（所有已分配内存）。
建议您在不需要内存时将其释放。
不要使用全局或静态变量。
BREW 结构不支持全局或静态变量，因为动态下载的应用程序无法处理这些数据类型。 此外，使用全局或静态变量可能导致连接器出现目标错误。 始终将持久数据存储在小程序结构中。
定义结构时不要初始化结构。
对于 ARM 编译器，定义并初始化的结构被视为静态数据。 请参阅上述“不要使用全局或静态变量”。
不要在条件语句内分配变量。
使用 ARM 编译器应避免此类问题。 不要在条件语句中编写赋值代码。
不要使用原始浮点运算。
与上述“不要使用全局变量”相同；此处包括类型转换。
使用 BREW 在助手函数中提供的浮点调用。
使用 BREW 提供的标准库函数。
由于目标设备上的 RAM 限制，您需要将编译后的代码大小控制到最小，因此应使用标准 C 库函数的 BREW 子集（如果已提供），而不要使用标准库函数。
避免出现类型强制转换错误。
由于 ARM 编译器处理隐式类型转换比大多数 Windows 编译器严格，因此要明确声明类型转换。 这样可以避免在从 Windows SDK 转换至 ARM 环境时发生编译错误。
检查返回值。
调用有返回值的 BREW API 方法时，应处理成功和失败时的返回值。
处理错误代码。
一些函数可能返回 void，因此应使用 BREW API GetLastError() 机制来识别错误。
文件和目录名称。
在 BREW 3.0 版中，BREW 支持区分大小写的文件名和目录。 具体通过使用 IFILEMGR API 的 fs: 命名规则来支持区分大小写的文件访问。有关详细信息，请参阅 BREW API 参考资料程序> BREW SDK >文档> BREW API 参考资料。‘,‘Arial,8‘,10,10,00000000,0xc0ffff)">联机帮助 。 之后请确保以下事项：
MIF 文件名和小程序目录名必须完全匹配（包括大小写）
如果您使用的是旧的命名规则（即不是基于 fs:） 访问文件，须保证应用程序中使用的文件名必须与磁盘上的文件名完全一致（为小写）。 使用此规则时，您的应用程序将无法访问磁盘上使用混合大小写名称的文件和目录。
如果想要使用大小写混合名称的文件和目录，必须使用 fs: 命名规则。
如果您在开发面向低于 BREW 3.0 的 BREW 版本的应用程序，请遵循以下规则：
BREW 仅支持使用小写名称的文件和目录。 因此，请确保只使用小写字符的文件和目录名。 BREW API 1.0.1.x 版本和更高版本采用对应用程序开发者透明的方式处理大小写问题。 不要使用带两个圆点 (.) 的文件名或带一个圆点 (.) 的数据库名。 这些字符由于未知问题而无法使用。
最小化代码大小。
要最小化代码的大小，请在将应用程序加载至目标设备前禁用调试信息选项。
设置警告级别。
在 Windows 中编译应用程序时，应将警告级别设为最高级，即 4 级。 此操作有助于更全面地检查代码。 由于 ARM 编译器在指示错误方面比 Windows 编译器更严格，因此应确保应用程序能够顺利地编译为 ARM 目标。
组合多次读写。
通过组合多次读写操作（如果可能），可以全面提高读写文件的效率。 将数据读入缓冲区，在需要时访问。
从第三方应用程序调用 MobileShop™
在 BREW 中，应用程序可以将自身注册为 MIME 类型（和 URL）的处理程序。 ISHELL_GetHandler() API 可用于查看应用程序是否将自身注册为指定 MIME 类型的处理程序；ISHELL_BrowseURL()API 可通过传递 URL 来调用注册的应用程序。
例如：
如果应用程序 A 将自身注册为 Aref MIME 类型的处理程序，应用程序 B 能够通过调用 ISHELL_GetHandler(pIShell, HTYPE_BROWSE, "Aref") 检查应用程序 A 是否在设备上以及是否注册为 Aref MIME 类型的处理程序，并通过调用 ISHELL_BrowseURL(pIShell, "Aref:foo")，使用 "foo" 参数启动应用程序 A。 结果，应用程序 A 将被 EVT_APP_START 事件启动（在 ((AEEAppStart*)dwParam)->pszArgs 中使用 "foo"），然后会收到传递给它的带有指向 URL 字符串 "Aref:foo" 的 dwParam 参数的 EVT_APP_BROWSE_URL 事件。
应用程序使用 ISHELL_GetHandler() 检测所支持的 MIME 类型，及使用 ISHELL_BrowseURL() 通过该 MIME 类型支持的 URL调用 MobileShop 的概念是实现应用程序使用 MobileShop 的核心。 下表提供应用程序可用于调用 MobileShop 的 URL 及有关说明。
MobileShop 1.x 将自身注册为 mshop MIME 类型的处理程序并处理以下 URL：
URL
详细信息
"mshop:Search=<搜索字符串>"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "mshop:Search=<搜索字符串>") 启动 MobileShop 1.x 来搜索应用程序或目录。 响应此命令的结果是向用户提供包含匹配搜索字符串的应用程序和目录名的搜索结果。
"mshop:ItemID=<下载项目 ID>"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "mshop:ItemID=<下载项目 ID") 启动 MobileShop 1.x 来显示其购买选项。由于 BREW 1.x 或 BREW 2.x 中应用程序不具备查找它们下载项目 ID 的搜索方法，所以在基于设备的 BREW 1.x 和 BREW 2.x 使用此 URL 时只能局限于部分应用程序，它们具备在应用程序下载服务器上查找其下载项目 ID 的其它搜索方法。 BREW 3.x 提供了 ISHELL_GetClassItemID()，使应用程序能够获得与应用程序ClassID 对应的下载项目 ID。
MobileShop 2.x 自注册为 cmshop MIME 类型的处理程序，它提供以下 URL 以方便第三方应用程序：
URL
详细信息
"cmshop:Catalog"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "cmshop:Catalog") 启动 MobileShop 2.x 来显示顶层目录。
"cmshop:Search"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "cmshop:Search") 启动 MobileShop 2.x 来显示搜索 UI。 响应此命令的结果是向用户提供 MobileShop 2.x 搜索 UI，用户可以从中搜索应用程序或目录。
"cmshop:ItemID=<下载项目 ID>"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "cmshop:ItemID=<下载项目 ID") 启动 MobileShop 2.x 来显示其购买选项。 由于 BREW 1.x 或 BREW 2.x 中应用程序不具备查找它们下载项目 ID 的搜索方法，所以在基于设备的 BREW 1.x 和 BREW 2.x 设备上使用此 URL 时只能局限于部分应用程序，它们具备在应用程序下载服务器上查找其下载项目 ID 的其它搜索方法。 BREW 3.x 提供了 ISHELL_GetClassItemID()，使应用程序能够获得与应用程序ClassID 对应的下载项目 ID。
"cmshop:UpgradeCheck=<下载项目 ID>"
应用程序可以通过调用 ISHELL_BrowseURL(pIShell, "cmshop:UpgradeCheck=<下载项目 ID") 启动 MobileShop 2.x 来显示其升级选项。 由于 BREW 1.x 或 BREW 2.x 中应用程序不具备查找它们下载项目 ID 的搜索方法，所以在基于设备的 BREW 1.x 和 BREW 2.x 上使用此 URL 时只能局限于部分应用程序，它们具备在应用程序下载服务器上查找其下载项目 ID 的其它搜索方法。 BREW 3.x 提供了 ISHELL_GetClassItemID()，使应用程序能够获得与应用程序ClassID 对应的下载项目 ID。
文件系统名称空间和 ACL
在 BREW 3.0 版中，规范的 BREW 文件名称空间以字符串 "fs:/" 开头，并允许在整个 BREW 文件系统内寻址。 以前，动态应用程序只限于 命名（及访问） 其所属模块目录下的文件和目录，不能命名共享 目录、振铃器目录以及地址簿目录。
有了 BREW 3.0，动态应用程序可以命名任何文件和目录，但是部分访问限制还是和以前版本相同，并应用了一些新的访问限制。 首要一点是，模块许可必须包含 PL_FILE，以便修改 BREW 文件系统。 模块可能在它们的主目录中发布或输出文件。截至 BREW 3.0，BREW 在各模块的 MIF 中查找 RESTYPE_BINARY 资源 IDB_MIF_ACLS（MIF 编辑器中的 ACL），以决定各许可可以发布的文件。
在该资源中，BREW 期望找到以双 NULL 结尾的字符串，语法如下：
ACLs          = (ACL ‘\0‘)+ ‘\0‘
ACL           = assignperms ":" path
path          = <单字节字符串>
assignperms   = assignperm [ ";" assignperms ]
assignperm    = groups "=" exactperms "/" subtreeperms
groups        = group [ "," group ]
group         = <十六进制数>
exactperms    = perms
subtreeperms  = perms
perms         = [+-] [r] [w]
请看以下 ACL 示例：
0x0=rw/rw:/
允许每个人均有权完全访问主目录。 ACL 有一个 assignperms 字段，其中有一个 group: 0（该特殊的 group 0 用于表示“全部组”）。 exactperms "rw" 实际是赋予对相关条目的 delete(!) 访问权限。
请看另一示例：
0x0=r/rw:/
此例与上例的不同之处在于，此例的 exactperms 中没有 "w"。 这个 ACL 表示： 任何人都可以读取主目录（枚举它），并可以读取、写入、创建或删除此目录下的任何内容。
这可能是最好的“公用”目录 ACL。
以下是一些 BREW 的 ACL（一般与 "fs:/" 有关）：
const char *cpszzBREWACL =
"0x00000000 =  r /    :/"             "\0" // 所有组要读取 fs:/，但不读取 fs:/ 以下
"0x00000000 =  r /  r :/mif"          "\0" // 所有组要读取 fs:/mif
"0x00000000 =  r /    :/mod"          "\0" // 所有组要读取 fs:/mod，但不读取 fs:/mod 以下
"0x00000020 = rw / rw :/sys/download" "\0" // PL_DOWNLOAD 要读取/写入 fs:/sys/download
"0x00000000 =  r /  r ;"                   // 所有组要读取 fs:/shared
"0x00000040 =  - / +w :/shared"       "\0" // PL_SHARED_WRITE 要在 fs:/shared 写入
"0x00000100 =  r / rw :/ringers"      "\0" // PL_RINGER_WRITE 要在 fs:/ringers 写入
"0x00000200 =  r / rw :/address"      "\0" // PL_ADDRBOOK 读取 fs:/address，所有 fs:/address 以下的访问
"0x0101414E =  r / rw :/card0"        "\0" // CARD0_ACCESS 读取 fs:/card0，所有 fs:/card0 以下的访问
;
注意冒号的左边，会忽略空白。 许可区为空表示赋值为“无许可”。 许可区为 "-" 表示没有对许可进行修改。
如果您想给每个人赋予特定子目录的读写权限，但又希望该目录特定部分 "super-secret-choco-fudgy-batcave"（完全访问权限仅限您的小组），此时应该怎么办？ 您需要为每个子树分配单独的 ACL，方法如下：
0x0=r/r:/public
0x0=/;0x00C110C0=rw/rw:/public/choco
第一条规则表示： “公布public”，与上述非常相似。 不过，第二条规则将覆盖第一条规则（规则是按顺序应用的）。 第二条规则拒绝所有人访问除 "00C110C0" 组内应用程序外的内容，该组被赋予完全访问 /public/choco 权限（包括删除 /public/choco 本身）。
由于 ACL 是按顺序应用的，所以 ACL 中也包含实用的 +- 功能。 该功能可用于重新表达 choco 示例：
0x0=r/r:/public
0x0=-r/-r;0x00C110C0=+rw/+rw:/public/choco
写入第二个规则的目的是对第一个规则进行修改： 它拒绝任何人对 00C110C0 的访问及添加写入权限。
注意以下事项：
路径必须以 "/" 开头，以便 ACL 解析代码使用。 否则，将无法匹配任何 BREW 路径。
‘+‘ 和 ‘-‘ 只有作为 perms 字段的第一个非空白字符才合法。
虽然名称不是目录的情况下 subtreeperms 字段是不相关的，但名称也不必一定是目录。
通过将组列在应用程序的“导入类”中，可使应用程序成为该组的一部分。 各应用程序同时还位于各自的组中（组相当于应用程序的 ClassID）。 有关详细信息，请参阅 BREW API 参考资料 程序 > BREW SDK > 文档 > BREW API 参考资料。‘,‘宋体,8‘,10,10,00000000,0xc0ffff)">联机帮助中的ISHELL_CheckPrivLevel()。
BREW SDK 的组件
BREW SDK 包含以下组件。
Simulator(模拟器)
BREW 头文件
资源编辑器
Visual Studio 插件
MIF 编辑器
BREW 实用程序
BREW DLL
ExpenseTracker\r\n> Hello World\r\n> MediaPlayer\r\n> Road Warrior\r\n> WhiteBoard\r\n> NetDiagnostics‘,‘宋体,10‘,10,10,00000000,0xc0ffff)">示例应用程序
BREW OEM DLL
联机帮助
组件如何交互
下图显示了 BREW SDK 的主要组件（MIF 编辑器、资源编辑器、C++ DE 和使用设备信息包的Simulator）以及它们之间的交互关系。
注意： 在该图中，testapp 代表一个使用 BREW 开发的应用程序。

_xyz