BREW 2.0 API 参考资料 简介

BREW 2.0 API 参考资料
简介

本文档为开发者提供了开发 BREW 设备平台应用程序所需的 Binary Runtime Environment for WirelessTM (BREWTM) 函数和数据结构的信息。

QUALCOMM Logo
Request New BREW SDK Features


在本参考资料中

BREW 2.0 API 参考资料的其余内容包括以下部分：

BREW API 接口 | 按字母顺序列出 BREW 接口和函数。
助手函数 | 按字母顺序详列助手函数。
数据类型 | 按字母顺序列出 BREW 接口使用的数据结构。

每个函数的说明均提供以下信息：

说明 | 函数用法的说明。
原型 | 调用结构的示例。
参数1 | 需要输入和返回的项目。
返回值 | 从函数调用返回的项目，包括多种类型、消息、值、结构和说明。
备注 | 帮助理解函数的用法、限制和边界的特殊说明和附加信息。
副作用 （仅在适当情况下） | 使用函数调用时函数表现的任何异常行为。 除非存在副作用，否则不显示该标题。
另请参阅 | 相关函数或数据结构的交叉参考。

1仅当参数表包含混合类型时，参数列表才显示 [in]、[in/out] 和 [out]。 如果表中都是输入参数，将省略 [in]。


BREW 继承函数

每个继承函数均链接至其基类。 以下是继承函数条目的一个示例。

IBITMAP_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表

IBITMAP_Release()

返回函数列表


BREW 文档集

BREW 文档集包含以下文档：

BREW SDK TM 用户指南 | 介绍 BREW 软件开发包 (BREW SDKTM) 组件及其相互关系。 该文档还包括开发 BREW 应用程序和使用 BREW Emulator 的常规说明。
BREW 2.0 API 参考资料 | 提供开发 BREW 移动平台应用软件所需的 BREW 函数和数据结构的信息。
BREW Device Configurator 指南 | 说明如何使用 BREW Device Configurator 创建有效的无线设备用于 BREW Emulator 的模拟。
BREW 资源编辑器指南 | 说明如何使用 BREW 资源编辑器创建 BREW 应用程序的文本字符串、图像和对话框。
BREW MIF 编辑器指南 | 说明如何使用 BREW MIF 编辑器创建和修改 MIF － BREW 资源文件的特殊类型，该文件包括特定 BREW 模块支持的类和小程序信息。
BREW SDK TM 实用程序指南 | 说明如何使用 BREW SDK 中的实用程序，如 PureVoice Converter。
BREW Compressed Image 编辑指南 | 说明如何使用 BREW Compressed Image 编辑工具创建应用程序用来显示和制作图像的文件。


详细信息

BREW 应用程序开发者可以获得各种联机信息和支持。 有关详细信息，请访问 BREW 网站： www.qualcomm.com/brew/developer。


请求 BREW 的新功能

如果您在使用 BREW SDK 的过程中对它的功能有任何更好更有价值的意见和想法， 欢迎您给我们发送电子邮件，地址是 brew-request@qualcomm.com。 新功能反应小组将认真考虑您的每一个意见，并通过电子邮件尽快地给予您答复。


BREW SDKTM AEE 分层结构图表

下表显示了 BREW SDK AEE 接口的分层结构：

IBase 接口 |  |  |  |
 | IAddrBook 接口 |  |  |
 | IAddrRec 接口 |  |  |
 | IApplet 接口 |  |  |
 | IBTAG 接口 |  |  |
 | ICipher 接口 |  |  |
 | IClipboard 接口 |  |  |
 | IDatabase 接口 |  |  |
 | IDBMgr 接口 |  |  |
 | IDBRecord 接口 |  |  |
 | IDialog 接口 |  |  |
 | IDisplay 接口 |  |  |
 | IFileMgr 接口 |  |  |
 | IGraphics 接口 |  |  |
 | IHash 接口 |  | 助手函数 |
 | IHeap 接口 |  |  |
 | IImage 接口 |  |  |
 | ILicense 接口 |  |  |
 | IModule 接口 |  |  |
 | IRamCache 接口 |  |  |
 | IRingerMgr 接口 |  |  |
 | IRSA 接口 |  |  |
 | IShell 接口 |  |  |
 | ISound 接口 |  |  |
 | ISoundPlayer 接口 |  |  |
 | IViewer 接口 |  |  |
 | IVocoder 接口 |  |  |
 | IAStream 接口 | IFile 接口 |  |
 |  | IMemAStream 接口 |  |
 |  | ISocket 接口 |  |
 |  | IUnzipAStream 接口 |  |
 | INotifier 接口 | INetMgr 接口 |  |
 |  | ITAPI 接口 |  |
 | IControl 接口 | IDateCtl 接口 |  |
 |  | IHtmlViewer 接口 |  |
 |  | IImageCtl 接口 |  |
 |  | IMenuCtl 接口 |  |
 |  | IStatic 接口 |  |
 |  | ITextCtl 接口 |  |
 |  | ITimeCtl 接口 |  |
 | IQueryInterface | IMedia 接口 | IMedia 格式 |
 |  | IBitmap 接口 | IDIB 接口 |
 |  | IBTSDP 接口 |  |
 |  | IDNS 接口 |  |
 |  | IFont 接口 |  |
 |  | IHashCTX 接口 |  |
 |  | ISprite 接口 |  |
 |  | ITransform 接口 |  |
 |  | IPosDet 接口 |  |
 |  | ISourceUtil 接口 |  |
 |  | IWebUtil 接口 |  |
 |  | WebOpts 列表 | ISSL 接口 |
 |  |  | IX509Chain 接口 |
 |  |  | IWeb 接口 |
 |  |  | IWebResp 接口 |
 |  |  | SSLRootCerts 接口 |
 |  | ISource 接口 | IBTSIOPORT 接口 |
 |  |  | IPeek 接口 | IGetLine 接口


IAddrBook 接口

IAddrBook 接口支持与 OEM 地址簿（设备上的主地址簿）进行交互， 但不支持多地址簿
功能。

IAddrBook 接口提供对地址记录集的访问。 地址记录包含保存在地址字段集中的数据。 每个地址记录均可归属某一类别（如“个人”和“商务”）。 支持的类别列表由 OEM 设定。 您可以使用 IADDRBOOK_EnumCategoryInit() 和 IADDRBOOK_EnumNextCategory() 来枚举 OEM 支持的类别。

地址记录中包含地址字段集，其中每个地址字段都拥有一个关联的 FieldID 和 FieldType。 FieldID 由数据类型 AEEAddrFieldID 标示。 OEM 可自行添加更多字段类型。

同一字段只能包含一个值。 如果需要地址记录存储多个家庭电话号码，则应为每个电话号码建立单独的地址字段。

类似地，如果一个电话号码既是工作电话又是家庭电话，则需使用两个地址字段分别表示“家庭”和“工作”信息。

IAddrBook 提供 BREW 接口来处理给定地址簿中的条目。 地址簿可包含一条或多条地址记录。

该接口可提供以下功能：

  • 枚举支持的地址类别
  • 枚举支持的字段类型
  • 为地址簿添加新记录
  • 根据指定字段和类别搜索地址簿
  • 浏览地址簿所有记录

要包含的头文件列表

需要以下头文件：

AEEAddrBook.h

函数列表

此接口的函数包括：

IADDRBOOK_AddRef()

IADDRBOOK_CreateRec()

IADDRBOOK_EnumCategoryInit()

IADDRBOOK_EnumFieldsInfoInit()

IADDRBOOK_EnumNextCategory()

IADDRBOOK_EnumNextFieldsInfo()

IADDRBOOK_EnumNextRec()

IADDRBOOK_EnumRecInit()

IADDRBOOK_GetLastError()

IADDRBOOK_GetNumRecs()

IADDRBOOK_GetRecById()

IADDRBOOK_Release()

IADDRBOOK_RemoveAllRecs()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IADDRBOOK_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IADDRBOOK_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IADDRBOOK_CreateRec()

说明：

此函数用于创建新的地址记录。

原型：

IAddrRec * IADDRBOOK_CreateRec
(
IAddrBook * pIAddrBook,
AEEAddrCat c,
AEEAddrField * pItems,
int nItemCount
)

参数：

pIAddrBook | 指向 IAddrBook 接口对象的指针。
c | 该地址所属类别。 AEE_ADDR_CAT_NONE 表示“未归类”。
pItems | 要加入地址簿的新地址记录的字段数组。
nItemCount | 字段数组 pItems 中的字段数

返回值：

如果成功，则返回指向新创建地址记录的 IAddrRec 指针。

如果失败，则返回 NULL。 这种情况下，可以调用 IADDRBOOK_GetLastError() 获取详细的错误信息。 可能的错误代码为 ENOMEMORY。

备注：

无

另请参阅：

AEEAddrCat

AEEAddrField

返回函数列表

IADDRBOOK_EnumCategoryInit()

说明：

此函数用于对设备地址簿支持的地址记录类别的枚举进行初始化。

原型：

int IADDRBOOK_EnumCategoryInit(IAddrBook * pIAddrBook)

参数：

pIAddrBook
指向 IAddrBook 接口对象的指针。

返回值：

如果枚举已初始化，则返回 AEE_SUCCESS。 现在可以使用 IADDRBOOK_EnumNextcategory() 获取有关支持的类别的信息。

如果不支持类别，则返回 AEE_ADDRBOOK_NOCATSUPPORT。

如果内存不够，则返回 ENOMEMORY。

如果发生任何其它常规错误，则返回 EFAILED。

备注：

无

另请参阅：

IADDRBOOK_EnumNextCategory()

返回函数列表

IADDRBOOK_EnumFieldsInfoInit()

说明：

此函数用于对地址簿中给定类别支持的字段的枚举进行初始化。

原型：

int IADDRBOOK_EnumFieldsInfoInit(IAddrBook * pIAddrBook, AEEAddrCat c)

参数：

pIAddrBook | 指向 IAddrBook 接口对象的指针。
c | 指定要枚举字段支持的类别。 如果此参数设置为 AEE_ADDR_CAT_NONE，则此函数将初始化对所有类别支持的字段枚举。

返回值：

如果枚举成功初始化，则返回 AEE_SUCCESS。 使用 IADDRBOOK_EnumNextFieldsInfo() 以获取支持字段的信息。

如果不支持类别，则返回 AEE_ADDRBOOK_NOCATSUPPORT。

如果内存不够，则返回 ENOMEMORY。

备注：

无

另请参阅：

AEEAddrCat

IADDRBOOK_EnumFieldsInfoInit()

返回函数列表

IADDRBOOK_EnumNextCategory()

说明：

此函数用于枚举设备地址簿支持的下一个地址记录类别。 在使用此函数之前，必须使用 IADDRBOOK_EnumCategoryInit() 初始化枚举。

原型：

boolean IADDRBOOK_EnumNextCategory
(
IAddrBook * pIAddrBook,
AEEAddrCat * pc
)

参数：

pIAddrBook | [in] | 指向 IAddrBook 接口对象的指针。
pc | [out] | 包含类别信息。

返回值：

如果找到新类别，则返回 TRUE。

没有其它类别可枚举，或者 pc 为 NULL，则返回 FALSE。

备注：

无

另请参阅：

AEEAddrCat

IADDRBOOK_EnumCategoryInit()

返回函数列表

IADDRBOOK_EnumNextFieldsInfo()

说明：

此函数用于枚举该类别支持的下一个字段。 它返回关于给定类别支持的字段信息。 在使用此函数之前，必须使用 IADDRBOOK_EnumFieldsInfoInit() 初始化枚举。

原型：

boolean IADDRBOOK_EnumNextFieldsInfo
(
IAddrBook * pIAddrBook,
AEEAddrFieldInfo * pf
)

参数：

pIAddrBook | [in] | 指向 IAddrBook 接口对象的指针。
pf | [in/out] | 输入时，该参数必须是指向 AEEAddrFieldInfo 结构的有效指针。 如果返回 TRUE 值，该参数将包含关于此类别支持的下一个字段类型的信息。

返回值：

如果找到新字段，则返回 TRUE。 这种情况下，* pf 包含字段信息。

没有其它字段可用于枚举，则返回 FALSE。

备注：

无

另请参阅：

AEEAddrFieldInfo

IADDRBOOK_EnumFieldsInfoInit()

返回函数列表

IADDRBOOK_EnumNextRec()

说明：

此函数用于枚举下一个与上次调用 IADDRBOOK_EnumRecInit() 时指定的搜索条件相匹配的记录。 在调用此函数之前，必须成功调用 IADDRBOOK_EnumRecInit() 函数。

原型：

IAddrRec * IADDRBOOK_EnumNextRec(IAddrBook * pIAddrBook)

参数：

pIAddrBook
指向 IAddrBook 接口对象的指针。

返回值：

如果找到匹配，则返回指向匹配的地址记录的 IAddrRec 指针。

如果函数失败，则返回 NULL。

备注：

无

另请参阅：

IADDRBOOK_EnumRecInit()

返回函数列表

IADDRBOOK_EnumRecInit()

说明：

此函数用于初始化对地址簿中符合指定的搜索条件的记录的枚举。 初始化枚举后，
可以使用 IADDRBOOK_EnumNextRec() 函数逐一访问与该搜索条件相匹配的记录。

原型：

int IADDRBOOK_EnumRecInit
(
IAddrBook * pIAddrBook,
AEEAddrCat wCategory,
AEEAddrFieldID wFieldID,
void * pData,
uint16 wDataSize
)

参数：

pIAddrBook | 指向 IAddrBook 接口对象的指针。
wCategory | 要匹配的类别类型。 设为 AEE_ADDR_CAT_NONE 时，则忽略。
wFieldID | 要匹配的 AEEAddrFieldID。 设为 AEE_ADDRFIELD_NONE 时，则忽略。 在此指定某个字段之前，必须先检验地址簿是否允许基于该字段进行搜索。 这一点可通过 IADDRBOOK_EnumFieldsInfoInit() 和 IADDRBOOK_EnumNextFieldsInfo() 函数实现。
pData | 如果非空，该参数将指定必须匹配的实际数据。 如果是 NULL，则 忽略。
wDataSize | 指定 sizeof(pData)。

预排地址簿中的所有记录

请使用以下代码：

IADDRBOOK_EnumRecInit
(
pIAddrBook,
AEE_ADDR_CAT_NONE,
AEE_ADDRFIELD_NONE,
NULL,0
);

预排拥有指定名称的所有记录

请使用以下代码：

IADDRBOOK_EnumRecInit
(
pIAddrBook,
AEE_ADDR_CAT_NONE,
AEE_ADDRFIELD_NAME,
azName, size
);

参数 aszName 是指向要搜索名称的 AECHAR * 指针，size 是数据的大小。

查找拥有指定电话号码的记录

请使用以下代码：

IADDRBOOK_EnumRecInit
(
pIAddrBook,
AEE_ADDR_CAT_NONE,
AEE_ADDRFIELD_NONE,
azNum, size
);

参数 azNum 是表示号码的字符串，size 表示号码的大小。

返回值：

如果找到匹配，则返回 AEE_SUCCESS。

如果失败，则返回 EFAILED。

备注：

通过为类别参数指定 AEE_ADDR_CAT_NONE，为字段参数指定 AEE_ADDRFIELD_NONE，该函数还可在数据库所有记录的范围内进行枚举。

另请参阅：

AEEAddrCat

AEEAddrFieldID

IADDRBOOK_EnumNextRec()

IADDRBOOK_EnumFieldsInfoInit()

IADDRBOOK_EnumNextFieldsInfo()

返回函数列表

IADDRBOOK_GetLastError()

说明：

此函数用于返回地址簿最新操作所产生的错误。

原型：

int IADDRBOOK_GetLastError(IAddrBook * pIAddrBook)

参数：

pIAddrBook
指向 IAddrBook 接口对象的指针。

返回值：

最近发生的错误。

备注：

无

另请参阅：

无

返回函数列表

IADDRBOOK_GetNumRecs()

说明：

此函数用于返回地址簿中的地址记录数。

原型：

int IADDRBOOK_GetNumRecs(IAddrBook * pIAddrBook)

参数：

pIAddrBook
指向 IAddrBook 接口对象的指针。

返回值：

地址簿中的地址记录数。

备注：

无

另请参阅：

无

返回函数列表

IADDRBOOK_GetRecById()

说明：

此函数用于检索指向具有指定 ID 的地址记录的指针。 可以使用 IADDRREC_GetRecID() 来获取记录的记录 ID。

原型：

IAddrRec * IADDRBOOK_GetRecById(IAddrBook * pIAddrBook, uint16 wID)

参数：

pIAddrBook | 指向 IAddrBook 接口对象的指针。
wID | 需从地址簿中检索的记录 ID。

返回值：

如果成功，则返回给定 ID 指定的地址记录的 IAddrRec 指针。

如果函数失败，则返回 NULL。 这种情况下，可以调用 IADDRBOOK_GetLastError() 获取详细的出错信息。可能返回的代码是 ENOMEMORY。

备注：

无

另请参阅：

IADDRREC_GetRecID()

返回函数列表

IADDRBOOK_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IADDRBOOK_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表

IADDRBOOK_RemoveAllRecs()

说明：

此函数用于删除给定地址簿中的所有记录。 由于该函数对地址簿影响很大，因此并非所有设备都支持该函数。 如果不支持该函数，则返回 EUNSUPPORTED 值。

原型：

int IADDRBOOK_RemoveAllRecs(IAddrBook * pIAddrBook)

参数：

pIAddrBook
指向 IAddrBook 接口对象的指针。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果不支持此功能，则返回 EUNSUPPORTED。

如果此操作失败，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表


IAddrRec 接口

IAddrRec 可以实现对地址记录中个别字段的访问。 它提供以下功能：

  • 为记录添加新字段
  • 更新现有地址记录的字段
  • 删除现有地址记录的字段
  • 更改记录的地址类别

要包含的头文件列表

需要以下头文件：

AEEAddrBook.h

函数列表

此接口的函数包括：

IADDRREC_AddField()

IADDRREC_AddRef()

IADDRREC_GetCategory()

IADDRREC_GetField()

IADDRREC_GetFieldCount()

IADDRREC_GetLastError()

IADDRREC_GetRecID()

IADDRREC_Release()

IADDRREC_RemoveField()

IADDRREC_RemoveRec()

IADDRREC_SetCategory()

IADDRREC_UpdateAllFields()

IADDRREC_UpdateField()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

IADDRREC_AddField()

说明：

此函数用于为记录添加新字段。

原型：

int IADDRREC_AddField(IAddrRec * pIAddrRec, AEEAddrField * pField)

参数：

pIAddrRec | 指向 IAddrRec 接口对象的指针。
pField | 记录要添加的新字段。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果是常规失败，则返回 EFAILED。

如果内存不足，则返回 ENOMEMORY。

备注：

无

另请参阅：

AEEAddrField

IADDRREC_UpdateField()

IADDRREC_RemoveField()

返回函数列表

IADDRREC_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表

IADDRREC_Release()

返回函数列表

IADDRREC_GetCategory()

说明：

此函数用于返回地址记录的类别。

原型：

AEEAddrCat IADDRREC_GetCategory(IAddrRec * pIAddrRec)

参数：

pIAddrRec
指向 IAddrRec 接口对象的指针。

返回值：

记录的地址类别。

备注：

无

另请参阅：

AEEAddrCat

返回函数列表

IADDRREC_GetField()

说明：

此函数用于检索给定索引处字段的信息。 索引的初始值为零，范围从零至 NumFields -1（其中 NumFields 是记录中的字段数）。 调用程序不可释放或更改此函数返回的指针。 释放记录时会自动释放该指针。 如果需要修改该字段，必须调用函数 IADDRREC_UpdateField() 使修改生效。

原型：

AEEAddrField * IADDRREC_GetField(IAddrRec * pIAddrRec, int nFieldIdx)

参数：

pIAddrRec | 指向 IAddrRec 接口对象的指针。
nFieldIdx | 指定要检索其信息的字段索引。 索引的初始值为 0（零）。

返回值：

如果成功，则返回指向当前索引位置的 AEEAddrField 指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

AEEAddrField

返回函数列表

IADDRREC_GetFieldCount()

说明：

此函数用于返回记录中的字段数。

原型：

int IADDRREC_GetFieldCount(IAddrRec * pIAddrRec)

参数：

pIAddrRec
指向 IAddrRec 接口对象的指针。

返回值：

记录中的字段数。

备注：

无

另请参阅：

无

返回函数列表

IADDRREC_GetLastError()

说明：

此函数用于返回在IAddrRec 接口上最新地址记录操作所产生的错误。

原型：

int IADDRREC_GetLastError(IAddrRec * pIAddrRec)

参数：

pIAddrRec
指向 IAddrRec 接口对象的指针。

返回值：

最近发生的错误。

备注：

无

另请参阅：

无

返回函数列表

IADDRREC_GetRecID()

说明：

此函数用于返回 IAddrRec 接口所指记录的 ID。

原型：

uint16 IADDRREC_GetRecID(IAddrRec * pIAddrRec)

参数：

pIAddrRec
[in]
指向 IAddrRec 接口对象的指针。

返回值：

记录的 ID。

备注：

无

另请参阅：

无

返回函数列表

IADDRREC_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IADDRREC_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表

IADDRREC_RemoveField()

说明：

此函数用于删除给定索引位置处的字段。 索引的初始值为零。

原型：

int IADDRREC_RemoveField(IAddrRec * pIAddrRec, int nFieldIdx)

参数：

pIAddrRec | [in] | 指向 IAddrRec 接口对象的指针。
nFieldx | [in] | 指定要删除字段的索引位置。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果是常规失败，则返回 EFAILED。

如果内存不足，则返回 ENOMEMORY。

备注：

无

另请参阅：

IADDRREC_UpdateField()

IADDRREC_AddField()

返回函数列表

IADDRREC_RemoveRec()

说明：

此函数用于删除地址簿中的地址记录。

原型：

int IADDRREC_RemoveRec(IADDRREC * pIAddrRec)

参数：

pIAddrRec
指向 IAddrRec 接口对象的指针。

1

返回值：

如果成功，则返回 AEE_SUCCESS。

如果是常规失败，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

IADDRREC_SetCategory()

说明：

此函数用于设置地址记录的地址类别。

原型：

int IADDRREC_SetCategory(IAddrRec * pIAddrRec, AEEAddrCat cat)

参数：

pIAddrRec | 指向 IAddrRec 接口对象的指针。
cat | 新的地址类别。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果失败，则返回 EFAILED。

备注：

无

另请参阅：

AEEAddrCat

返回函数列表

IADDRREC_UpdateAllFields()

说明：

此函数用于更新记录中的全部字段。 它使用传递来的新字段来替换记录中的全部
字段。

原型：

int IADDRREC_UpdateAllFields
(
IAddrRec * pIAddrRec,
AEEAddrField * pFields,
int nFieldCount
)

参数：

IAddrRec | 指向 IAddrRec 接口对象的指针。
pFields | 指定字段的更新信息。 此函数使用这些新字段来替换全部现有字段。
nFieldCount | 指定 pFields 数组中需要添加到记录的字段数。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果因内存不足而无法执行该操作，则返回 ENOMEMORY。

如果是常规失败，则返回 EFAILED。

备注：

无

另请参阅：

AEEAddrField

IADDRREC_UpdateField()

返回函数列表

IADDRREC_UpdateField()

说明：

此函数用于更新给定索引位置的字段。 索引的初始值为零。

原型：

int IADDRREC_UpdateField
(
IAddrRec * pIAddrRec,
int nFieldIdx,
AEEAddrField * pf
)

参数：

pIAddrRec | [in] | 指向 IAddrRec 接口对象的指针。
nFieldIdx | [in] | 指定要更新的新字段的索引。
pf | [in] | 指定字段的更新信息。 此函数使用新字段来替换索引所指的现有字段。

返回值：

如果成功，则返回 AEE_SUCCESS。

如果因内存不足而无法执行该操作，则返回 ENOMEMORY。

如果是常规失败，则返回 EFAILED。

备注：

无

另请参阅：

AEEAddrField

IADDRREC_UpdateAllFields()

返回函数列表


IApplet 接口

IApplet 接口是在应用程序执行环境 (AEE) 下处理事件的接口。 该接口由 IBase 派生，可以实现一个简单事件处理例程。 AEE 外壳调用该例程来响应系统、其它组件或小程序生成的事件。 BREW AEE 中的所有小程序都必须实现该接口。 换句话说，BREW 小程序是实现 IApplet 接口的类。BREW AEE 外壳使用 IAPPLET_HandleEvent() 向小程序发送事件。

注意： IAPPLET_HandleEvent() 只能由 AEE 外壳调用。 由其他小程序或组件发送的事件可以通过 ISHELL_SendEvent() 来发送。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

此接口的函数包括：

IAPPLET_AddRef()

IAPPLET_HandleEvent()

IAPPLET_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

IAPPLET_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IAPPLET_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IAPPLET_HandleEvent()

说明：

此函数用于为 BREW 小程序处理主要事件。 在向小程序传递事件时即会调用此函数。 事件可以包括系统级通知、按键事件等等。

系统警报或系统通知调用此函数来响应。 如果小程序当前未在运行，则会加载该小程序并向它发送事件。 但是，不会向小程序发送 EVT_APP_STOP 事件，除非小程序自己启动，并且在事件完成后，小程序将终止运行。 所有小程序都必须实现 IAPPLET_HandleEvent() 函数。

IAPPLET_HandleEvent() 函数还用于支持小程序启动、停止、中止和恢复。

原型：

boolean IAPPLET_HandleEvent
(
IApplet * pIApplet,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIApplet | 指向 IApplet 接口对象的指针。
evt | 事件代码。
wp | 16 位事件特定参数。
dwp | 32 位事件特定参数。

返回值：

如果小程序已处理事件，则返回 TRUE。

否则，返回 FALSE。

如果操作未处理事件，则返回 FALSE 可以让 AEE 进一步处理该事件， 这一点非常重要。 典型的示例是接收到 AVK_CLR 事件时， 如果应用程序未处理该事件，返回 FALSE 将帮助 AEE 关闭应用程序。

备注：

此函数只能由 AEE 外壳调用。

另请参阅：

ISHELL_SendEvent()

AEE 事件

返回函数列表

IAPPLET_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IAPPLET_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表


IAStream 接口

IAStream 接口可读取异步流中的数据。 它是由一些类所实现的抽象接口，这些类可以对无法同时访问而必须异步检索的数据提供访问。 目前，由 IFile 和 ISocket 类实现 IAStream 接口。 IImage 接口和 ISoundPlayer 接口 实现了 IIMAGE_SetStream() 和 ISOUNDPLAYER_SetStream() 函数，允许将 IAStream 接口作为图像或声音输入源。

IASTREAM_Read() 读取流中的数据并返回读取的字节数。 如果没有数据可以读取，此函数将返回 AEE_STREAM_WOULDBLOCK 值。 在后一种情况下，调用 IASTREAM_Readable() 可以调度有更多可用数据时调用的回调函数。IASTREAM_Cancel() 则可以取消使用 IASTREAM_Readable()调用的回调函数。

使用 IAStream 实例异步检索数据

  1. 调用 ISHELL_CreateInstance() 创建一个实现 IAStream 接口的类的实例。
  2. 调用 IASTREAM_Read() 从流中读取要求的数据字节数。 由于 IAStream 接口是抽象接口，因此对于文件，请调用 IFILE_Read()；对于套接字，请调用 ISOCKET_Read()。
  3. 如果 IASTREAM_Read() 返回 AEE_STREAM_WOULDBLOCK，调用 IASTREAM_Readable() 调度一个回调，稍后再试。
  4. 如果 IASTREAM_Read() 读取的字节数少于要求的字节数，再次调用此函数读取余下的数据。
  5. 重复步骤 2 至 4，直到流中所有的数据都被检索。

使用异步流作为图像或声音数据源

  1. 调用 ISHELL_CreateInstance() 创建一个实现 IAStream 接口的类的实例。
  2. 调用 ISHELL_CreateInstance() 创建 IImage 接口或 ISoundPlayer 接口的实例。
  3. 调用 IIMAGE_Notify() 或 ISOUNDPLAYER_RegisterNotify() 调度一个在检索全部图像或声音数据后调用的回调。
  4. 调用 IIMAGE_SetStream() 或 ISOUNDPLAYER_SetStream() 关联步骤 1 创建的流和步骤 2 创建的 IImage 或 ISoundPlayer 实例，以初始化对流中的图像或声音数据的检索。
  5. 完成检索后，调用步骤 3 中注册的回调。 使用 IImage 接口或 ISoundPlayer 接口中的函数访问检索的图像或声音数据。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

此接口的函数包括：

IASTREAM_AddRef()

IASTREAM_Cancel()

IASTREAM_Read()

IASTREAM_Readable()

IASTREAM_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

IASTREAM_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IASTREAM_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IASTREAM_Cancel()

说明：

此函数用于取消 IASTREAM_Readable() 调度的回调。

原型：

void IASTREAM_Cancel(IAStream * pIAStream, PFNNOTIFY pfn, void * pUser)

参数：

pIAStream | 指向 IAStream 接口对象的指针。
pfn | 指向要取消回调的回调函数的指针。
pUser | 指向用户指定数据的指针，该数据作为参数传递给回调函数，用于标识必须取消的回调。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IASTREAM_Read()

IASTREAM_Readable()

返回函数列表

IASTREAM_Read()

说明：

此函数用于尝试从流中读取数据，并返回读取的字节数。 如果没有数据可以读取，则返回 AEE_STREAM_WOULDBLOCK 值。

原型：

int32 IASTREAM_Read
(
IAStream * pIAStream,
void * pBuffer,
uint32 dwCount
)

参数：

pIAStream | 指向 IAStream 接口对象的指针。
pBuffer | 指向读取数据的缓冲区的指针。
dwCount | 读取的字节数。

返回值：

如果数据可读取，则返回已读取的字节数。

如果已经读取所有可读取数据，则返回 0（零）。

如果当前没有可以读取的数据，则返回 AEE_STREAM_WOULDBLOCK。

备注：

无

另请参阅：

IASTREAM_Readable()

IASTREAM_Cancel()

返回函数列表

IASTREAM_Readable()

说明：

此函数用于注册一个回调来检验是否有可读取的数据。 如果 IASTREAM_Read() 返回 AEE_STREAM_WOULDBLOCK，则调用该函数。

原型：

void IASTREAM_Readable
(
IAStream * pIAStream,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIAStream | 指向 IAStream 接口对象的指针。
pfn | 指向回调函数的指针。
pUser | 指向用户指定数据的指针，该数据作为参数传递给回调函数。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IASTREAM_Read()

IASTREAM_Cancel()

返回函数列表

IASTREAM_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IASTREAM_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表


IBase 接口

IBase 是派生所有其它 BREW AEE 接口的底层接口。 它提供的对象引用计数机制，允许对象管理其内存实例。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

此接口的函数包括：

IBASE_AddRef()

IBASE_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

IBASE_AddRef()

说明：

此函数可增加 IBase 接口对象的引用计数，以便多个调用程序共享该对象。 引用计数为 0（零）时将释放该对象。 请参阅IBASE_Release()。

原型：

uint32 IBASE_AddRef(IBase * pIBase)

参数：

pIBase
指向 IBase 接口对象的指针。

返回值：

已增加的对象引用计数。

备注：

有效对象返回的引用计数为正值。

另请参阅：

IBASE_Release()

返回函数列表

IBASE_Release()

说明：

此函数用于减少 IBase 接口对象的引用计数。 引用计数为 0（零）时，将从内存中释放该对象且不再有效。

原型：

uint32 IBASE_Release(IBase * pIBase)

参数：

pIBase
指向 IBase 接口对象的指针

返回值：

已减少的对象引用计数。

如果该对象已被释放，且不再有效，则返回 0（零）。

备注：

无

另请参阅：

IBASE_AddRef()

返回函数列表


IBitmap 接口

此接口可以操作位图。 每个 IBitmap 实例均代表一个位图。 IBitmap 是具有多种实现的接口。 一类是使用 IDISPLAY_CreateDIBitmap() 创建的设备无关位图 (DIB)，另一类是代表耳机显示的位图。 虽然这两类位图均实现 IBitmap 接口，但它们具有不同的功能。 DIB 和显示位图都可以执行块移动操作。 显示位图支持所有绘制操作，而 DIB 通常不支持绘制，并在多数函数中返回 EUNSUPPORTED。 所有返回错误代码的函数都可能返回 EUNSUPPORTED。 用户应该对所有错误代码类型做好准备。

要包含的头文件列表

需要以下头文件：

AEEBitmap.h

函数列表

此接口的函数包括：

IBITMAP_AddRef()

IBITMAP_BltIn()

IBITMAP_BltOut()

IBITMAP_CreateCompatibleBitmap()

IBITMAP_DrawHScanline()

IBITMAP_DrawPixel()

IBITMAP_FillRect()

IBITMAP_GetInfo()

IBITMAP_GetPixel()

IBITMAP_GetTransparencyColor()

IBITMAP_NativeToRGB()

IBITMAP_QueryInterface()

IBITMAP_Release()

IBITMAP_RGBToNative()

IBITMAP_SetPixels()

IBITMAP_SetTransparencyColor()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IBITMAP_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IBITMAP_Release()

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IBITMAP_BltIn()

说明：

此函数可以将对应于像素矩形的数据从指定的源位图位块传输到此位图中。 源中每个像素均与目标中的相应像素关联。 在每对源和目标像素上执行逻辑操作，并将结果写到目标像素上。

原型：

int IBITMAP_BltIn
(
IBitmap * pIBitmap,
int xDst,
int yDst,
int dx,
int dy,
IBitmap *pSrc,
int xSrc,
int ySrc,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向需要进行位块传输的 IBitmap 接口对象的指针。
xDst | [in] | 指定目标矩形区域左上角的 x 坐标。
yDst | [in] | 指定目标矩形区域左上角的 y 坐标。
dx | [in] | 指定目标和源矩形的宽度。 负值将作为零处理。
dy | [in] | 指定目标和源矩形的高度。 负值将作为零处理。
pSrc | [in] | 指向其它代表源位图的 IBitmap 接口的指针。
xSrc | [in] | 指定必须从中开始传输位块的源位图左上角的 x 坐标。
ySrc | [in] | 指定必须从中开始传输位块的源位图左上角的 y 坐标。
rop | [in] | 指定在执行位块传输时使用的光栅操作。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

如果不支持该操作，则返回其它错误代码。 这可能是由于源位图的格式或请求的光栅操作类型有问题，也可能是由于同时出现这两种情况。

备注：

如果 dx 或 dy 为负，则目标位图中不会写入任何内容。 矩形将作为空处理。

对于所有或部分落在对应位图界限之外的源或目标矩形，包含负坐标是合法的。

超出位图界限的源或目标矩形部分将被剪切。 剪切不会影响所有未剪切部分从源至目标的映射，并且不会导致产生错误代码（即使矩形已全部剪切）。

如果源位图的宽度和高度未知，要位块传输整个位图，则需要为 dx 和 dy 设定很大的值，然后剪切将把矩形限制为源位图的大小。

源位图与目标位图的格式可能相同，也可能不同，但不一定支持所有源格式。

另请参阅：

AEERasterOp

IBITMAP_BltOut()

返回函数列表

IBITMAP_BltOut()

说明：

执行从该位图到指定目标位图的位块传输。 用户通常不会直接调用此函数， 而是调用目标位图的 IBITMAP_BltIn() 成员函数，因为这种方法在更多的情况下会成功。

原型：

int IBITMAP_BltOut
(
IBitmap * pIBitmap,
int xDst,
int yDst,
int dx,
int dy,
IBitmap *pDst,
int xSrc,
int ySrc,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向要进行位块传输的 IBitmap 接口对象的指针。
xDst | [in] | 指定目标矩形区域左上角的 x 坐标。
yDst | [in] | 指定目标矩形区域左上角的 y 坐标。
dx | [in] | 指定目标矩形的宽度。
dy | [in] | 指定目标矩形的高度。
pDst | [in] | 指向其它代表目标位图的 IBitmap 接口的指针。
xSrc | [in] | 指定必须从中开始传输位块的源位图左上角的 x 坐标。
ySrc | [in] | 指定必须从中开始传输位块的源位图左上角的 y 坐标。
rop | [in] | 指定在执行位块传输时使用的光栅操作。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码

备注：

除实现 IBITMAP_BltIn() 外，其它情况下不必调用此函数。 IBITMAP_BltOut() 正是用于辅助 IBITMAP_BltIn()。 如果目标不支持 IBITMAP_BltIn() 操作，并且位图属于不同类，则 IBITMAP_BltIn() 的操作将由源位图的 IBITMAP_BltOut() 代为实现。 通过这种方式，两类位图都有可能执行该操作，并且只要其中一类支持即可成功。 请注意，IBITMAP_BltOut() 不能委托 IBITMAP_BltIn() 实现，因为这将导致无限递归。

另请参阅：

AEERasterOp

IBITMAP_BltIn()

返回函数列表

IBITMAP_CreateCompatibleBitmap()

说明：

此函数用于创建与此位图接口（第一个参数）兼容的新位图。 兼容是指具有相等的像素大小和相同的像素值（本地颜色）与 RGB 值间映射。 宽度和高度不影响兼容性。 两个兼容位图之间的位块传输操作速度相当快，因为它无需执行像素数据的复杂转换。 作为一种常用的操作类型，它通常经过高度优化。 而且，兼容位图之间的复制不会导致丢失任何颜色信息。 兼容位图通常会支持原始位图所支持的全部相同绘制操作。

原型：

int IBITMAP_CreateCompatibleBitmap
(
IBITMAP *pIBitmap,
IBitmap **ppIBitmap,
uint16 w,
uint16 h
)

参数：

pIBitmap | [in] | 指向当前位图接口的指针。
ppIBitmap | [out] | 指向与当前位图具有相同格式的新位图接口的指针。
w | [in] | 新位图的宽度。
h | [in] | 新位图的高度。

返回值：

如果函数正确执行，则返回 SUCCESS。

否则，将返回错误代码。

如果无足够内存来执行该操作，则返回 ENOMEMORY。

其它特定于实现的错误代码。

备注：

无

另请参阅：

无

返回函数列表

IBITMAP_DrawHScanline()

说明：

此函数用于绘制水平线段。

原型：

int IBITMAP_DrawHScanline
(
IBitmap *pIBitmap,
unsigned y,
unsigned xMin,
unsigned xMax,
NativeColor color,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向用于绘制水平线段的 IBitmap 接口对象的指针。
y | [in] | 线段 Y 坐标。
xMin | [in] | 线段左端的 X 坐标。
xMax | [in] | 线段右端的 X 坐标。
color | [in] | 指定用于绘制线段的颜色。 这是本地颜色，可通过 IBITMAP_RGBToNative() 获取。
rop | [in] | 指定用于绘制线段的光栅操作。 只有 AEE_RO_COPY 和 AEE_RO_XOR 有效。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码

备注：

无

另请参阅：

AEERasterOp

返回函数列表

IBITMAP_DrawPixel()

说明：

此函数用于在位图中绘制单个像素。

原型：

int IBITMAP_DrawPixel
(
IBitmap *pIBitmap,
unsigned x,
unsigned y,
NativeColor color,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向需要绘制像素的 IBitmap 接口的指针。
x | [in] | 像素的 X 坐标。
y | [in] | 像素的 Y 坐标。
color | [in] | 指定用于绘制像素的颜色。 这是本地颜色，可通过 IBITMAP_RGBToNative() 获取。
rop | [in] | 指定用于绘制像素的光栅操作。 只有 AEE_RO_COPY 和 AEE_RO_XOR 有效。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

如果光栅操作无效，则返回 EBADPARM。

备注：

如果 x 或 y 位于位图界限之外，则不绘制任何内容，并返回 SUCCESS。

另请参阅：

AEERasterOp

IBITMAP_GetPixel()

IBITMAP_DrawPixel()

返回函数列表

IBITMAP_FillRect()

说明：

此函数用于绘制指定颜色的实心矩形。

原型：

int IBITMAP_FillRect
(
IBitmap *pIBitmap,
const AEERect *prc,
NativeColor color,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向用于填充矩形的 IBitmap 接口对象的指针。
prc | [in] | 指向需要使用指定颜色填充的矩形的有效指针
color | [in] | 指定用于填充矩形的颜色。 这是本地颜色，可通过 IBITMAP_RGBToNative() 获取。
rop | [in] | 指定绘制矩形时使用的光栅操作。 只有 AEE_RO_COPY 和 AEE_RO_XOR 有效。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果 color 为 NULL，则返回 EBADPARM。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码。

备注：

prc 参数必须为有效指针。 落在位图界限之外的任何矩形部分将自动忽略（不生成
错误）。

另请参阅：

AEERasterOp

返回函数列表

IBITMAP_GetInfo()

说明：

此函数用于检索位图的大小。

原型：

int IBITMAP_GetInfo
(
IBitmap * pIBitmap,
AEEBitmapInfo * pinfo,
int nSize
)

参数：

pIBitmap | [in] | 指向 IBitmap 接口的指针。
pinfo | [out] | 指向 AEEBitmapInfo 的指针，其中包含宽度、高度、颜色 深度等。
nSize | [in] | 当前版本中 sizeof(AEEBitmapInfo) 的大小。 AEEBitmapInfo 结构可能会随时间而增大。 此字段保证了向后兼容性。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果位图未识别大小，则返回 EUNSUPPORTED。

备注：

如果 nSize 等于 sizeof(AEEBitmapInfo)，并且 pinfo 为有效指针，此函数将始终
成功。

另请参阅：

AEEBitmapInfo

返回函数列表

IBITMAP_GetPixel()

说明：

此函数用于检索指定像素值。

原型：

int IBITMAP_GetPixel
(
IBitmap *pIBitmap,
unsigned x,
unsigned y,
NativeColor *pColor
)

参数：

pIBitmap | [in] | 指向要绘制像素的 IBitmap 接口的指针。
x | [in] | 像素的 X 坐标。
y | [in] | 像素的 Y 坐标。
pColor | [out] | 指定像素的颜色。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果坐标超出范围，则返回 EBADPARM。

如果不支持该操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码。

备注：

无

另请参阅：

IBITMAP_SetPixels()

返回函数列表

IBITMAP_GetTransparencyColor()

说明：

此函数用于获取位图的当前透明色。 如果此位图为透明位块移动操作的源位图，则需要使用此函数。

原型：

int IBITMAP_GetTranparencyColor
(
IBITMAP *pMe,
NativeColor *pColor
)

参数：

pMe | [in] | 指向当前位图接口的指针。
pColor | [out] | 透明色。

返回值：

如果函数正确执行，则返回 SUCCESS。

否则，将返回错误代码。

如果 pColor 为 NULL，则返回 EBADPARM。

如果不支持该操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码

备注：

该透明色为 NativeColor 值，而不是 RGBVAL。

副作用：

无。

另请参阅：

IBITMAP_BltIn()

IBITMAP_BltOut()

IBITMAP_SetTransparencyColor()

返回函数列表

IBITMAP_NativeToRGB()

说明：

此函数用于以 RGBVAL 格式获取 NativeColor 值的 RGB 定义。

每个有效 NativeColor 均对应了一个 RGB 值。 NativeColor 值的映射为位图属性。

原型：

RGBVAL IBITMAP_NativeToRGB(IBitmap *pIBitmap, NativeColor clr)

参数：

pIBitmap | [in] | 指向 IBitmap 接口的指针。
clr | [in] | 本地颜色值。

返回值：

相应的 RGBVAL。

备注：

如果提供的 NativeColor 没有关联特定的 RGB 值，则此函数将返回未定义值。

另请参阅：

NativeColor

RGBVAL

IBITMAP_RGBToNative()

返回函数列表

IBITMAP_QueryInterface()

说明：

此函数用于检索指向符合指定 ClassID 定义的接口的指针。 它可以用来查询扩展功能，如未来版本或专有功能。 查询成功时，将返回该接口。 调用程序负责在将来调用 Release()。 返回指针不是接口指针的情况除外。 在这种情况下，内存与正被查询的对象具有相同的使用期，所返回的指针将不用于释放对象。

原型：

int IBITMAP_QueryInterface(IBitmap *pIBitmap, AEECLSID id, void **p);

参数：

pIBitmap | [in] | 指向 IBitmap 接口的指针。
id | [in] | 标识正被查询的实体（接口或数据）的全局唯一 id。
p | [out] | 指向要检索的数据或接口的指针。 如果传递回的值为 NULL，则表示所查询的接口或数据不存在。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

备注：

许多位图支持 IDIB 接口（类 id： AEECLSID_DIB) ，该接口包含的公有数据允许调用程序直接访问位图数据。 只有内部格式符合所说明的 IDIB 格式之一的位图才能支持 IDIB。 对于其它接口，用户使用完 IDIB 后必须将 IDIB 释放。

如果失败，*pIBitmap 将设置为 NULL。但最好在调用 IBITMAP_QueryInterface()
之前将 *pIBitmap 明确设置为 NULL。

另请参阅：

无

返回函数列表

IBITMAP_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IBITMAP_AddRef()

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IBITMAP_RGBToNative()

说明：

此函数用于将 RGBVAL 转换为本地颜色值（像素值）。 本地颜色值是指存储在像素数组中的值；本地和 RGB 值间的映射是位图的一个属性。 如果与指定 RGBVAL 完全对应的 NativeColor 不存在，则将返回接近匹配的值。 不要求此函数返回最接近的匹配。出于性能的原因，它可能返回接近（但不是最接近）的匹配。

原型：

NativeColor IBITMAP_RGBToNative(IBitmap *pIBitmap, RGBVAL RGBColor)

参数：

pIBitmap | [in] | 指向 IBitmap 接口的指针。
RGBColor | [in] | 要转换的 RGB 值。 只支持实际 RGB 值。 不支持颜色表索引。

返回值：

对应的本地颜色值。

备注：

如果位图缺少调色板信息，则结果未定义。

另请参阅：

RGBVAL

IBITMAP_NativeToRGB()

返回函数列表

IBITMAP_SetPixels()

说明：

此函数用于绘制多个颜色相同的像素。

原型：

int IBITMAP_SetPixels
(
IBitmap *pIBitmap,
unsigned cnt,
AEEPoint *pPoint,
NativeColor color,
AEERasterOp rop
)

参数：

pIBitmap | [in] | 指向需要绘制像素的 IBitmap 接口对象的指针。
cnt | [in] | 像素数目。
pPoint | [in] | 二维点数组。
color | [in] | 指定用于绘制多个输入像素的颜色。 这是本地颜色，可通过 IBITMAP_RGBToNative() 获取。
rop | [in] | 指定用于绘制像素的光栅操作。 只有 AEE_RO_COPY 和 AEE_RO_XOR 有效。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码

备注：

只有 AEE_RO_COPY 和 AEE_RO_XOR 为有效的光栅操作。 其它任何作为参数传递的值的处理方式与 AEE_RO_COPY 类似。 当前版本中，此函数将返回 EUNSUPPORTED。

另请参阅：

AEERasterOp

IBITMAP_GetPixel()

返回函数列表

IBITMAP_SetTransparencyColor()

说明：

此函数用于设置位图的透明色。 如果此位图为透明位块传输操作的源位图，则需要使用此函数。 对于包含此 NativeColor 的像素，其对应目标像素不受影响。

原型：

int IBITMAP_SetTranparencyColor(IBITMAP *pMe, NativeColor color);

参数：

pMe | [in] | 指向当前位图接口的指针。
color | [in] | 作为透明色的颜色。

返回值：

如果函数正确执行，则返回 SUCCESS。

否则，将返回错误代码。

如果不支持指定的光栅操作，则返回 EUNSUPPORTED。

其它特定于实现的错误代码

备注：

无。

另请参阅：

NativeColor

IBITMAP_BltIn()

IBITMAP_BltOut()

IBITMAP_GetTransparencyColor()

返回函数列表


IBTAG 接口

IBTAG 接口函数用于打开、关闭和管理耳机的 BluetoothTM音频网关。

要使用 IBTAG 接口，请执行以下操作：

  1. 使用 IBTAG_Open 打开 Bluetooth 音频网关端口。
  2. 使用 IBTAG_SendCommand 发送命令。
  3. 对于任何事件，重复使用 IBTAG_GetEvent() 检索所有事件，直到用户获取 AEEBT_EV_AG_NOEVENTS。

要包含的头文件列表

需要以下头文件：

AEEBTAG.h

函数列表

此接口的函数包括：

IBTAG_AddRef()

IBTAG_GetEvent()

IBTAG_GetLastError()

IBTAG_Open()

IBTAG_QueryInterface()

IBTAG_Release()

IBTAG_SendCommand()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

IBTAG_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IBTAG_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表。

IBTAG_GetEvent()

说明：

此函数用于获取设备上发生的事件代码。

原型：

int32 IBTAG_GetEvent(IBTAG *pIBTAG, AEEBTAGEvent* pevt)

参数：

pIBTAG | 指向 IBTAG 接口对象的指针。 |
pevt | 事件代码的返回值。 |
 | 以下为有效返回值： |
 | AEEBT_EV_AG_NOEVENTS | Bluetooth 堆栈中无其它事件。
 | AEEBT_EV_AG_ENABLED | 已启用 Bluetooth 音频网关。
 | AEEBT_EV_AG_DISABLED | 已禁用 Bluetooth 音频网关。
 | AEEBT_EV_AG_HEADSET_PICKUP | 用户已连接耳机。
 | AEEBT_EV_AG_DISCONNECT_REQUEST | 用户已断开耳机连接。
 | AEEBT_EV_AG_AUDIO_CONNECTED | 已连接音频通道。
 | AEEBT_EV_AG_AUDIO_DISCONNECTED | 已断开音频通道连接。
 | AEEBT_EV_AG_AUDIO_CONN_TIMEOUT | 音频连接超时。
 | AEEBT_EV_AG_ERROR | 命令处理期间出错。

返回值：

如果函数成功，则返回 SUCCESS。

如果函数获取事件失败，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

IBTAG_GetLastError()

说明：

此函数用于获取最后一个错误代码。

原型：

int32 IBTAG_GetLastError(IBTAG *pIBTAG)

参数：

pIBTAG
指向 IBTAG 接口对象的指针。

返回值：

指定 Bluetooth 音频网关接口上最后一个错误的错误代码。 有关错误代码的信息，请参阅 AEEError.h。

备注：

无

另请参阅：

无

返回函数列表

IBTAG_Open()

说明：

打开使用 Bluetooth 的音频网关。

原型：

int32 IBTAG_Open
(
IBTAG *pBTAG,
AEEBTAGInfo* pBTAGInfo,
AEECallback *pcb
)

参数：

pBTAG | 指向 IBTAG 接口对象的指针。
pBTAGInfo | 有关耳机的连接信息。
pcb | 此端口上发生任何事件时调度的回调。 如果用户取消此回调，将无法再使用该端口。

返回值：

SUCCESS：

EFAILED： 打开音频网关失败。

备注：

无

另请参阅：

无

返回函数列表

IBTAG_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约

原型：

int IBTAG_QueryInterface
(
IBTAG * pIBTAG,
AEECLSID idReq,
void * * ppo
)

参数：

pIBTAG | [in] | 指向 IBTAG 接口对象的指针。
idReq | [in] | 对象显露的被请求的 ClassID。
ppo | [in/out] | 返回的对象。 由此函数填写。

返回值：

如果已找到接口，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT。

备注：

无

另请参阅：

无

返回函数列表

IBTAG_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IBTAG_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表

IBTAG_SendCommand()

说明：

该函数用于发送一条命令。

原型：

int32 IBTAG_SendCommand
(
IBTAG *pIBTAG, AEEBTAGCmd cmdcode, uint32 cmdval
);

参数：

pIBTAG | 指向 IBTAG 接口对象的指针
cmdcode | 命令代码。 以下为有效值：
 | AEEBT_CMD_RING_HEADSET | 使耳机发出铃声。
 | AEEBT_CMD_AUDIO_CONNECT， | 连接音频通道。
 | AEEBT_CMD_SET_SPKR_GAIN， | 增大/减小扬声器增益。
 | AEEBT_CMD_SET_HS_GAIN， | 增大/减小耳机增益。
 | AEEBT_CMD_DISCONNECT | 断开音频网关连接。
cmdval | 作为命令参数的 32 位值。 只有以下命令可以使用此参数：
 | AEEBT_CMD_SET_SPKR_GAIN |
 | AEEBT_CMD_SET_HS_GAIN |

返回值：

如果成功，则返回 SUCCESS。

如果发送命令失败，则返回 EFAILED。

发生响应以上命令的事件时，应调度该回调。 在回调中，用户应调用 IBTAG_GetEvent() 从事件队列中读取事件。

返回值：

SUCCESS：

EFAILED： 发送命令失败。

备注：

无

另请参阅：

无

返回函数列表


IBTSDP 接口

IBTSDP 接口函数用于发现 Bluetooth 设备以及查询设备名和相关服务器通道。

要发现设备，请执行以下操作

  1. 创建 IBTSDP 接口
  2. 根据请求设备的数量分配相应大小的 AEEBTDeviceListResult 结构。
  3. 初始化一个需要在完成发现设备时安排的 AEE 回调。
  4. 使用相应参数调用函数 IBTSDP_DiscoverDevices()。
  5. 完成发现时，调度回调。 执行回调时，检查 AEEBTDeviceListResult 结构。

要查询设备名称，请执行以下操作

  1. 创建 IBTSDP 接口。
  2. 分配 AEEBTDeviceNameResult 结构。
  3. 初始化一个需要在完成发现设备时安排的 AEE 回调。
  4. 使用相应参数调用函数 IBTSDP_GetDeviceName()。
  5. 完成发现时，调度回调。 执行回调时，检查 AEEBTDeviceNameResult 结构。

要查询远程服务器通道，请执行以下操作

  1. 创建 IBTSDP 接口。
  2. 分配 AEEBTServerChannelResult 结构。
  3. 初始化一个需要在完成发现设备时安排的 AEE 回调。
  4. 使用相应参数调用函数 IBTSDP_GetRemoteServerChannel()。
  5. 当完成发现时，调度回调。 执行回调时，检查 AEEBTServerChannelResult 结构。

要包含的头文件列表

需要以下头文件：

AEEBTSDP.h

函数列表

此接口的函数包括：

IBTSDP_AddRef()

IBTSDP_DiscoverDevices()

IBTSDP_GetDeviceName()

IBTSDP_GetRemoteServerChannel()

IBTSDP_QueryInterface()

IBTSDP_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IBTSDP_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IBTSDP_Release()

BREW SDKTM AEE 分层结构图表。

返回函数列表。

IBTSDP_DiscoverDevices()

说明：

开始发现 Bluetooth 设备的过程。

原型：

int32 IBTSDP_DiscoverDevices
(
IBTSDP *pIBTSDP,
uint8 maxDevices,
AEECallback *pcb,
AEEBTDeviceListResult *pResult
)

参数：

pIBTSDP | 指向 IBTSDP 接口对象的指针。
maxDevices | 要发现的最大设备数。 当前最大值为 4。
pcb | 完成发现时应调度的回调。
pResult | 指向结果记录的指针。 用户应分配 AEEBTDeviceListResult 记录。

返回值：

如果调度发现时没有出现任何错误，则返回 SUCCESS。

如果发现失败，则返回 EFAILED。

回调将 Bluetooth 设备发现的响应存储在 pResult 中。

备注：

无

另请参阅：

AEECallback

AEEBTDeviceListResult

返回函数列表

IBTSDP_GetDeviceName()

说明：

开始查询特定设备的 Bluetooth 名称。

原型：

int32 IBTSDP_GetDeviceName
(
IBTSDP *pIBTSDP,
AEEBTAddr *pbd_addr,
AEECallback *pcb,
AEEBTDeviceNameResult *pResult
)

参数：

pIBTSDP | 指向 IBTSDP 接口对象的指针。
pbd_addr | 用于查询的 Bluetooth 设备地址。
pcb | 完成发现时应调度的回调。
pResult | 指向结果记录的指针。 用户应分配 AEEBTDeviceNameResult 记录。

返回值：

如果调度查询时没有出现任何错误，则返回 SUCCESS。

如果查询失败，则返回 EFAILED。

回调将存储 Bluetooth 设备名称查询的响应。

备注：

无

另请参阅：

AEEBTAddr

AEECallback

AEEBTDeviceNameResult

返回函数列表

IBTSDP_GetRemoteServerChannel()

说明：

开始查询 Bluetooth 服务器通道。

原型：

int32 IBTSDP_GetRemoteServerChannel
(
IBTSDP *pIBTSDP,
AEEBTAddr *pbdaddr,
uint16 service_class,
AEECallback *pcb,
AEEBTServerChannelResult *pResult
)

参数：

:

pIBTSDP | 指向 IBTSDP 接口对象的指针。
pbd_addr | 用于查询的 Bluetooth 设备地址。
serviceclass | 用于查询的服务类别。
pcb | 完成发现时应调度的回调。
pResult | 指向结果记录的指针。 用户应分配 AEEBTServerChannelResult 记录。

返回值：

如果调度查询时没有出现任何错误，则返回 SUCCESS。

如果查询失败，则返回 EFAILED。

在执行回调时， 用户可以在 pResult 中检查 Bluetooth 服务器通道查询的响应。AEECallback 将存储 Bluetooth 设备查询的响应。

另请参阅：

AEEBTAddr

AEECallback

AEEBTServerChannelResult

返回函数列表

IBTSDP_QueryInterface()

说明：

此函数继承于 IQI_QueryInterface()。

另请参阅：

BREW SDKTM AEE 分层结构图表。

返回函数列表

IBTSDP_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IBTSDP_AddRef()

BREW SDKTM AEE 分层结构图表。

返回函数列表。


IBTSIOPORT 接口

IBTSIOPORT 接口函数用于通过 Bluetooth 串行接口执行打开、关闭、读取和写入等操作。

要使用此接口

  1. 使用 IBTSIOPORT_Open() 打开串行端口。
  2. 使用 IBTSIOPORT_Readable() 或 IBTSIOPORT_Writeable() 调度可写回调或可读回调。
  3. 成功建立连接后，可读或可写回调即已调度。 用户可以相应地读取或写入串行
    端口。
  4. 使用 IBTSIOPORT_GetState() 查询端口的状态
  5. 使用 IBTSIOPORT_Release() 关闭端口。

要包含的头文件列表

需要以下头文件：

AEEBTSIO.h

函数列表

此接口的函数包括：

IBTSIOPORT_AddRef()

IBTSIOPORT_GetState()

IBTSIOPORT_Open()

IBTSIOPORT_Read()

IBTSIOPORT_Readable()

IBTSIOPORT_Release()

IBTSIOPORT_Write()

IBTSIOPORT_Writeable()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IBTSIOPORT_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IBTSIOPORT_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IBTSIOPORT_GetState()

说明：

此函数用于返回 Bluetooth 端口的当前状态。

原型：

int32 IBTSIOPORT_GetState(IBTSIOPort * pIBTSIOPort);

参数：

pIBTSIOPort
端口

返回值：

Bluetooth 端口的状态。

AEEBT_ST_IDLE： 该连接空闲。

AEEBT_ST_LISTENING： 该连接处于监听模式。

AEEBT_ST_CONNECTING： 正在尝试建立连接。

AEEBT_ST_CONNECTED： 已连接至远程设备。

AEEBT_ST_CLOSED： 该连接已关闭。

备注：

无

另请参阅：

无

返回函数列表

IBTSIOPORT_Open()

说明：

此函数用于打开 Bluetooth 串行端口。

原型：

int32 IBTSIOPORT_Open
(
IBTSIOPort *pIBTSIOPort,
AEEBTConnectionInfo *pConnectInfo,
AEECallback *pcb
)

参数：

pIBTSIOPort | 指向 IBTSIOPORT 接口对象的指针。
pConnectInfo | Bluetooth 串行端口的连接信息。
pcb | 链接发生状态更改时调用的回调。 端口成功打开后才能调用 该回调。

返回值：

如果成功，则返回 SUCCESS。

如果出现错误，则返回 EFAILED。

备注：

无

另请参阅：

AEEBTConnectionInfo

AEECallback

返回函数列表

IBTSIOPORT_Read()

说明：

此函数用于将接收缓冲区中的数据，复制到调用程序所提供的 pcBuf[] 缓冲区中。 应尽可能多地复制可用数据，但不允许超过 nLen 字节，也不允许超过接收缓冲区中的可用字节数。 已复制到 pcBuf[] 的数据应从接收缓冲区中删除。

原型：

int32 IBTSIOPORT_Read
(
IBTSIOPort * pIBTSIOPort,
char *pcBuf,
int16 nLen
)

参数：

pIBTSIOPort | 指向 IBTSIOPORT 接口对象的指针。
pcBuf | 调用程序提供的缓冲区。
nLen | 输入缓冲区的字节数。 该值不应超过接收缓冲区大小。

返回值：

从接收缓冲区中删除的字节数。

如果接收缓冲区为空，则不必复制字节，此函数将返回 AEE_BT_WOULDBLOCK。

如果端口出现错误，则返回 AEE_BT_ERROR。

备注：

无

另请参阅：

IBTSIOPORT_Write()

返回函数列表

IBTSIOPORT_Readable()

说明：

此函数在数据可用时调度读回调。 它允许用户在端口数据可用时调度函数的异步调用。 执行该回调后，将把它从未完成的回调列表中删除。 用户应尽可能多地读取数据，然后使用此函数调度其它回调。

原型：

void IBTSIOPORT_Readable
(
IBTSIOPort *pIBTSIOPort,
AEECallback* pcb
)

参数：

pIBTSIOPort | 指向 IBTSIOPORT 接口对象的指针
pcb | 链接发生状态更改时调用的回调。 端口成功打开后才能调用 此回调。

返回值：

无

备注：

无

另请参阅：

IBTSIOPORT_Writeable()

返回函数列表

IBTSIOPORT_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IBTSIOPORT_AddRef()

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IBTSIOPORT_Write()

说明：

它将把 pcBuf 缓冲区中的 nLen 字节附加到传输缓冲区末尾。 如果缓冲区无法容纳 nLen 字节，则附加最大可容纳字节数。

原型：

int32 IBTSIOPORT_Write
(
IBTSIOPort *pIBTSIOPort,
char *pcBuf,
int16 nLen
)

参数：

pIBTSIOPort | 指向 IBTSIOPORT 接口对象的指针
pcBuf | 调用程序提供的缓冲区
nLen | 输入缓冲区的字节数。 该值不应超过接收缓冲区大小。

返回值：

附加到传输缓冲区的字节数。

如果接收缓冲区已满，并且未复制字节，则返回 AEE_BT_WOULDBLOCK。

如果端口出现错误，则返回 AEE_BT_ERROR。

备注：

无

另请参阅：

IBTSIOPORT_Read()

返回函数列表

IBTSIOPORT_Writeable()

说明：

当 Bluetooth 设备准备再次传输数据时，此函数将调度写回调。 它允许用户在数据传输就绪时调度函数的异步调用。 执行该回调后，将把它从未完成回调列表中删除。 用户应尽可能多写数据，然后使用此函数调度其它回调。

原型：

void IBTSIOPORT_Writeable
(
IBTSIOPort *pIBTSIOPort,
AEECallback* pcb
)

参数：

pIBTSIOPort | 指向 IBTSIOPORT 接口对象的指针
pcb | 链接发生状态更改时调用的回调。 端口成功打开后才能调用 此回调。

返回值：

无

备注：

无

另请参阅：

IBTSIOPORT_Readable()

返回函数列表


ICipher 接口

ICipher 接口的函数可以使 BREW 开发者无需知道加密算法的实质，便能灵活地实现加密或
解密。

ICipher 的实例可以使用 ISHELL_CreateInstance() 创建，该函数将一个 32 位的 ClassID 作为一个输入参数。 该 32 位 id 用于决定 ICipher 提供的服务类型。 如果 ISHELL_CreateInstance() 成功，则返回一个 ICipher 接口指针。 该接口指针用于调用 ICipher 函数。 调用 ICIPHER_Init() 可以设置密钥。 初始化密钥后，调用 ICIPHER_Cipher() 对数据进行加密或解密。 ICipher 完成后，应调用 ICIPHER_Release()。

要包含的头文件列表

需要以下头文件：

AEESecurity.h

函数列表

此接口的函数包括：

ICIPHER_AddRef()

ICIPHER_Cipher()

ICIPHER_Flush()

ICIPHER_Init()

ICIPHER_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ICIPHER_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

ICIPHER_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

ICIPHER_Cipher()

说明：

使用以前初始化的密钥加密或解密数据。 对于流密码（如 ArcFour），建议输出缓冲区大小至少为输入数据的长度。 否则，仅处理长度等于输出缓冲区大小的数据。

对于块密码，此函数的作用取决于特定的算法。 对于有 64 位块大小的 DES（尚不支持），此函数每次处理一个块并在输入输出端缓冲一个块大小的数据。 这样可以逐步输入或输出数据，并使输入数据长度和输出缓冲区大小都小于一个块的大小。 但是建议输出缓冲区至少为一个块的大小。

此函数返回处理过的输入字节数。 如果返回 0（零），除非写出以前处理的数据，否则无法处理新输入的数据。 如果发生这种情况，请不更改输入再次调用此函数。 如果在调用 ICipher_Flush() 后调用此函数，则不使用新的输入。 之前存在的待处理数据将通过密码算法传递。

原型：

int ICIPHER_Cipher
(
ICipher* pICipher,
const byte *pchIn,
int cbIn,
byte *pchOut,
int* pcbOut
)

参数：

pICipher | [in] | 指向 ICipher 接口对象的指针。
pchIn | [in] | 指向要加密或解密的数据的指针。
cbIn | [in] | 输入数据大小（字节数）。
pchOut | [out] | 接收加密/解密数据的缓冲区。
pcbOut | [in/out] | 输出大小（字节数）。

返回值：

如果函数遇到无效的加密/解密密钥，将返回 -1。 但是，如果在初始化无效密钥之前初始化的上一个密钥为有效密钥，则函数将把上一个密钥用作当前密钥，在这种情况下，不会返回 -1。

已处理的输入字节数计数。

备注：

无

另请参阅：

无

返回函数列表

ICIPHER_Flush()

说明：

在加密进程中使用块密码，用预先确定的字节填充前一个未处理的块以构成完整的块。 如果块已经完整（DES 采用 64 位），则不执行此函数。

原型：

void ICIPHER_Flush()

参数：

void

返回：

void：

备注：

无

另请参阅：

无

返回函数列表

ICIPHER_Init()

说明：

使用 ArcFour 初始化加密或解密的密钥。 ArcFour 密钥长度通常为 1 到 256 个字节。因为内部表中的字节交换包括密钥内容，所以密钥内容直接影响 ArcFour 的内部状态表。 BREW 执行的 ArcFour 现在将密钥长度限制为 256 个字节。 在调用 ICIPHER_Cipher() 之前，请先调用此函数。

原型：

int ICIPHER_Init(ICipher* pICipher, const byte* pchKey, int cbKey)

参数：

pICipher | 指向 ICipher 接口对象的指针。
pchKey | 指向密钥的指针。
cbKey | 密钥长度（以字节为单位）。

返回值：

如果 RSA 密钥初始化成功，将返回 SUCCESS。

如果函数遇到无效密钥，将返回 AEE_CRYPT_INVALID_KEY。

如果函数遇到内存过小而无法进行操作的情况，将返回 ENOMEMORY。

备注：

无

另请参阅：

无

返回函数列表

ICIPHER_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

ICIPHER_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表


IClipboard 接口

此接口用于实现 AEE 中的剪切和粘贴功能。

要包含的头文件列表

需要以下头文件：

AEEClipboard.h

函数列表

该接口的函数包括：

ICLIPBOARD_AddRef()

ICLIPBOARD_Empty()

ICLIPBOARD_EnumInit()

ICLIPBOARD_EnumNext()

ICLIPBOARD_GetData()

ICLIPBOARD_GetSequence()

ICLIPBOARD_MaxFreeBlock()

ICLIPBOARD_Release()

ICLIPBOARD_SetData()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

ICLIPBOARD_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

ICLIPBOARD_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

ICLIPBOARD_Empty()

说明：

从剪贴板中删除所有格式的全部数据。

原型：

int ICLIPBOARD_Empty(IClipboard* pIClipboard)

参数：

pIClipboard
指向 IClipboard 接口对象的指针。

返回值：

如果剪贴板已清空，则返回 SUCCESS。

如果剪贴板未清空，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

ICLIPBOARD_EnumInit()

说明：

此函数用于初始化剪贴板中格式的枚举上下文。

原型：

boolean ICLIPBOARD_EnumInit(IClipboard * pIClipboard)

参数：

pIClipboard
指向 IClipboard 接口对象的指针

返回值：

始终返回 TRUE。

备注：

无

另请参阅：

ICLIPBOARD_EnumNext()

返回函数列表

ICLIPBOARD_EnumNext()

说明：

此函数返回下一个可用/已注册的剪贴板格式。

原型：

boolean ICLIPBOARD_EnumNext
(
IClipboard * pIClipboard,
CBItemInfo * pci
)

参数：

pIClipboard
指向 IClipboard 接口对象的指针
pci
指向要填入的项目信息的指针。在调用此函数之前，必须正确设置 pci 参数（例如 CBItemInfo 结构）的成员 pszName 和 nNameLen。 返回时，pszName 将包含格式的名称，nDataSize 将包含数据的实际大小。
  • 输入时：
    • pci->pszName 必须为可以容纳字符串的有效指针。
    • pci->nNameLen 指定指针
      pci->pszName 可容纳的大小（以字节为单位）
  • 返回时：
    • pci->pszName 包含格式名称
    • pci->nDataLen 包含剪贴板中该格式的数据大小。

返回值：

如果返回格式，则返回 TRUE。

如果不存在下一项，则返回 FALSE。

备注：

无

另请参阅：

CBItemInfo

ICLIPBOARD_EnumInit()

返回函数列表

ICLIPBOARD_GetData()

说明：

将指定剪贴板格式的剪贴板数据复制到目标缓冲区。 所复制的大小将在大小参数中返回。

  • 如果传递的目标为 NULL，则将目标大小填入大小参数。
  • 如果传递的目标大小太小，则返回错误。

原型：

int ICLIPBOARD_GetData
(
IClipboard* pIClipboard,
const char * pszName,
void* pData,
int * pnDest
)

参数：

pIClipboard | 指向 IClipboard 接口对象的指针
pszName | 格式名称
pData | 指向目标数据缓冲区的指针
pnDest | 目标缓冲区的输入大小和所复制的输出大小。

返回值：

如果成功，则返回 0（零）

如果不支持该格式，则返回 EFAILED。

如果函数包含无效参数，则返回 EBADPARM

如果传递给函数的缓冲区大小不够，则返回 ENOMEMORY

备注：

无

另请参阅：

无

返回函数列表

ICLIPBOARD_GetSequence()

说明：

返回剪贴板的序列号。 此函数使得调用程序能够确定是否已更新剪贴板。 更新剪贴板包括数据的添加或删除。

原型：

uint32 ICLIPBOARD_GetSequence(IClipboard* pIClipboard)

参数：

pIClipboard
指向 IClipboard 接口对象的指针

返回值：

剪贴板的序列号

备注：

无

另请参阅：

无

返回函数列表

ICLIPBOARD_MaxFreeBlock()

说明：

返回空闲块大小的最大值。 填写指向剪贴板总大小（字节）和已用总大小（字节）的指针。

原型：

uint32 ICLIPBOARD_MaxFreeBlock
(
IClipboard* pIClipboard,
uint32 * pdwTotal,
uint32 * pdwUsed
)

参数：

pIClipboard | 指向 IClipboard 接口对象的指针
pdwTotal | 将要填入剪贴板内存总计大小（字节）的指针 （如果非 NULL）
pdwUsed | 将要填入剪贴板已用总空间的指针（如果非 NULL）

返回值：

剪贴板中最大空闲内存块的大小。

备注：

无

另请参阅：

无

返回函数列表

ICLIPBOARD_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

ICLIPBOARD_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表

ICLIPBOARD_SetData()

说明：

设置剪贴板格式的数据。 由于剪贴板数据在程序结束后仍然存在，因此该函数将分配新内存并将内容复制到新的缓冲区中。

注意：

  • 如果传递 NULL 指针或 0 大小，则将释放现有的剪贴板数据。
  • 与此格式已关联的数据将被释放。

原型：

int ICLIPBOARD_SetData
(
IClipboard* pIClipboard,
const char * pszName,
void* pData,
int nSize
)

参数：

pIClipboard | 指向 IClipboard 接口对象的指针
pszName | 格式名称
pData | 数据指针
nSize | 数据对象的大小

返回值：

如果已复制数据，则返回 0（零）

如果 pszName 为 Null，或没有足够的 RAM，则返回 EBADPARM

备注：

无

另请参阅：

无

返回函数列表


IControl 接口

IControl 接口是一个抽象接口，由每个 BREW 控件接口（IDateCtl 接口、IMenuCtl 接口、IStatic 接口、ITextCtl 接口和 ITimeCtl 接口）实现。 因其抽象性，所以不可能直接创建 IControl 接口的实例。 给定一个指向控件接口实例的指针，可以使用 IControl 函数或该控件接口中的某个函数调用 IControl 接口函数。 例如，通过调用 ICONTROL_Redraw() 或 IMENUCTL_Redraw() 可以刷新菜单控件。 如果要对很多不同类型的控件执行相同的操作，IControl 函数将十分有用。 例如，假设数组 pControls[numControls] 中包含指向必须在屏幕上一起显示的各种控件的指针。 那么可以使用以下循环刷新全部控件：

for (i = 0; i < numControls; i++)
ICONTROL_Redraw(pControls[i])

每个 BREW 控件都执行 IControl 接口的全部函数。 但是，每个接口的每个函数的行为都不相同；详细信息请参阅每个控件接口的函数说明。 每个 BREW 控件也可以执行不属于 IControl 接口的控件函数。

IControl 接口函数包括：

  • ICONTROL_HandleEvent()，用于向控件传递事件。 BREW 控件处理各种按键事件，使设备用户可以输入文本、时间、日期值或者从菜单中选择菜单项。 关于每个控件可以处理的事件，请参阅控件的说明。 控件只能在激活的状态下接收事件。 除非控件是对话框的一部分，否则小程序必须在控件激活时向其传递可处理的事件。
  • ICONTROL_Redraw()，用于刷新屏幕上的控件。 即重新显示改写后的控件。
  • ICONTROL_SetActive()，用于设置控件的激活状态（激活或非激活）。 只有激活的控件才能接收并处理事件。 对于多控件对话框，当前有焦点的控件才是激活的控件。
  • ICONTROL_IsActive()，用于获取控件的激活状态。
  • ICONTROL_SetRect()，用于设置显示控件的屏幕矩形的像素尺寸。 像素尺寸在 AEERect 结构中指定，该结构作为参数传递给此函数。 当控件的内容超出矩形范围时，某些控件提供了滚动机制。 通过适当设置矩形大小，可以在屏幕上同时显示多个控件。
  • ICONTROL_GetRect()，用于获取控件当前的矩形。
  • ICONTROL_SetProperties()，可以使您更改控件的属性值，启用某些可选功能后，这些值用于自定义控件的行为和外观。 每个控件最多可拥有 32 种属性，分别由 32 位变量中的一位表示。ICONTROL_SetProperties() 可以设置变量的值。 这些属性均未进行初始设置，通过打开属性位可以设置属性。 每个 BREW 控件都有一组不同的属性；有关每个控制支持的属性列表，请参阅控件的说明。 每个 BREW 控件的头文件都有一组位掩码常量，用于测试和设置与每个属性对应的位值。
  • ICONTROL_GetProperties()，用于获取控件属性值的当前值。 要设置某个属性，但不改变其它属性的值，请执行以下操作：
\t   dwProps = ICONTROL_GetProperties(pIControl);    ICONTROL_SetProperties(pIControl,(dwProps | PROP_BITMASK));
  • 其中 pIControl 是控件的指针，而 PROP_BITMASK是要设置的属性的位掩码。
  • ICONTROL_Reset()，用于释放与控件相关的全部资源，但不释放其接口指针。 此函数可用于重新初始化控件。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

此接口的函数包括：

ICONTROL_AddRef()

ICONTROL_GetProperties()

ICONTROL_GetRect()

ICONTROL_HandleEvent()

ICONTROL_IsActive()

ICONTROL_Redraw()

ICONTROL_Release()

ICONTROL_Reset()

ICONTROL_SetActive()

ICONTROL_SetProperties()

ICONTROL_SetRect()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

ICONTROL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

ICONTROL_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

ICONTROL_GetProperties()

说明：

此函数可以返回特定于控件的属性或标记。

原型：

uint32 ICONTROL_GetProperties(IControl * pIControl)

参数：

pIControl
指向 IControl 接口对象的指针。

返回值：

32 位的控件属性。

备注：

无

另请参阅：

ICONTROL_SetProperties()

返回函数列表

ICONTROL_GetRect()

说明：

此函数可以为输入 AEERect 结构的指针填入控件激活的屏幕坐标。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

原型：

void ICONTROL_GetRect(IControl * pIControl, AEERect * prc)

参数：

pIControl | 指向 IControl 接口对象的指针。
prc | 要填入控件坐标的矩形。

返回值：

无

备注：

无

另请参阅：

AEERect

ICONTROL_SetRect()

返回函数列表

ICONTROL_HandleEvent()

说明：

此函数用于处理控件的主要事件。 向控件传递事件时即会调用此函数。 事件主要包括按键事件。 所有控件都必须实现此函数。

原型：

boolean ICONTROL_HandleEvent
(
IControl * pIControl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIControl | 指向 IControl 接口对象的指针。
evt | 事件代码。
wp | 16 位事件数据。
dwp | 32 位事件数据。

返回值：

如果控件已处理该事件，则返回 TRUE。

否则，将返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ICONTROL_IsActive()

说明：

此函数用于返回控件的激活或焦点状态。

原型：

boolean ICONTROL_IsActive(IControl * pIControl)

参数：

pIControl
指向 IControl 接口对象的指针。

返回值：

如果控件处于激活状态，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ICONTROL_Redraw()

说明：

此函数用于指示控件刷新其内容。 一般情况下，如果支持控件的底层数据发生变化，用户接口控件并不刷新其内容。 目的是在更新若干数据时，使屏幕闪烁降至最低。 例如，除非调用 Redraw 函数，否则用户看不到添加到菜单的若干项目。

原型：

boolean ICONTROL_Redraw(IControl * pIControl)

参数：

pIControl
指向 IControl 接口对象的指针。

返回值：

如果控件已处理该事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ICONTROL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

ICONTROL_AddRef()

BREW SDKTM AEE 分层结构图表

返回函数列表

ICONTROL_Reset()

说明：

此函数用于指示控件清除（释放或删除）其内容，并立即离开激活或焦点模式。 这在释放文本或菜单控件中的全部基本内存或删除单一调用中的全部菜单项时十分有用。

原型：

void ICONTROL_Reset(IControl * pIControl)

参数：

pIControl
指向 IControl 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

ICONTROL_SetActive()

返回函数列表

ICONTROL_SetActive()

说明：

此函数用于指示控件进入或离开焦点或选定的模式。 控件使用焦点概念的情况多一些。 对于菜单，焦点表示菜单是激活的。 对文本控件而言，则表示控件是激活的并处于编辑模式。 调用此函数通常会使基本控件刷新其内容。

注意：即使控件处于非激活状态，仍可调用其事件处理函数，以处理一些特殊事件（如滚动多行文本控件）。

原型：

void ICONTROL_SetActive(IControl * pIControl,boolean bActive)

参数：

pIControl | 指向 IControl 接口对象的指针。
bActive | 指定激活 (TRUE) 控件，还是停用 (FALSE) 控件。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ICONTROL_SetProperties()

说明：

此函数用于设置特定于控件的属性或标记。 尽管某些属性是跨控件（CP_FRAME 等）定义的，但大多数控件都显露一部分属性以便对对象实施更具体的控制。

原型：

void ICONTROL_SetProperties(IControl * pIControl, uint32 dwProps)

参数：

pIControl | 指向 IControl 接口对象的指针。
dwProps | 32 位标记或属性组。

返回值：

无

备注：

无

副作用：

可能刷新控件。

另请参阅：

ICONTROL_GetProperties()

返回函数列表

ICONTROL_SetRect()

说明：

此函数用于设置控件的激活屏幕坐标。 这样可能会导致控件刷新其内容。

原型：

void ICONTROL_SetRect(IControl * pIControl, const AEERect * prc)

参数：

pIControl | 指向 IControl 接口对象的指针。
prc | 控件的绑定矩形。

返回值：

无

备注：

无

副作用：

可能刷新控件。

另请参阅：

AEERect

ICONTROL_GetRect()

返回函数列表


IDatabase 接口

IDatabase 接口函数使您可以创建和访问由 IDBMgr 接口创建并打开的数据库中的记录。 要获取 IDatabase 接口的实例，可以调用 IDBMGR_OpenDatabase() 打开指定的数据库， 然后使用由该函数返回的 IDatabase 接口指针访问该数据库，有关的操作请参阅本节后面的说明。 另外，还可以使用 IDBRecord 接口的函数访问个别数据库记录的字段。 完成数据库访问之后，调用 IDATABASE_Release() 关闭数据库。

注意：应用程序必须具有 PL_FILE 或 PL_SYSTEM 优先级， 才能调用此接口的函数来修改数据库内容。

IDATABASE_CreateRecord() 函数创建新的记录并将其添加到数据库中（函数 IDBRECORD_Remove() 用于删除数据库中的记录）。 每个记录可包含一个或多个字段。 每个字段由 AEEDBField 结构定义，该结构包括以下元素：

  • 字段名称是字段内容（姓名、电话号码及电子邮件地址等等）的描述符。AEEDBFieldName 枚举的类型包含常用字段名常量。
  • 字段类型给出字段（字节、字、双字、字符串、二进制、电话号码或位图）的数据类型。
  • 字段缓冲区指针是指向实际字段内容的指针。
  • 字段长度是字段内容的字节长度。

创建一个记录，便会增加一个 AEEDBField 结构的数组，以指定该记录中每个字段的名称、类型、内容和长度。 然后调用 IDATABASE_CreateRecord()，提供一个指向数组的指针及其包含的 AEEDBField 结构数作为输入信息。IDATABASE_CreateRecord() 返回一个指向 IDBRecord 接口实例的指针，该接口用于访问和更新记录字段。 在创建或更新记录后，会为每个记录指定字段数和字段类型；并不要求给定数据库中的全部记录都具有相同的结构。

在创建数据库并在其中添加记录后，使用其他 IDatabase 函数检索数据库中的记录。

检索数据库中的每个记录，请执行以下操作

  1. 调用 IDATABASE_Reset() 将记录指针设为 0（零）。
  2. 重复调用 IDATABASE_GetNextRecord() 为数据库的每个记录获取一个 IDBRecord 接口 指针。枚举全部记录后，IDATABASE_GetNextRecord() 将返回 NULL。

每个数据库记录在创建时都将分配一个唯一 ID（使用 IDBRECORD_GetID() 函数可以获取记录的 ID）。IDATABASE_GetRecordByID() 使您可以利用给定的 ID 检索数据库记录，返回可用来访问记录的 IDBRecord 接口指针。IDATABASE_GetRecordCount() 将返回数据库中的记录数。

要使用 IDatabase 接口的函数，请执行以下操作

  1. 如有必要，调用 ISHELL_CreateInstance() 获取 IDBMgr 接口的实例。
  2. 调用 IDBMGR_OpenDatabase() 或 IDBMGR_OpenDatabaseEx() 获取一个指向新的或现有数据库的 IDatabase 接口指针。
  3. 调用 IDATABASE_CreateRecord() 创建新记录，并将其添加到步骤 2 中打开的数据库。
  4. 调用 IDATABASE_Reset() 和 IDATABASE_GetNextRecord() 枚举数据库中的全部记录。 例如，查找匹配特定标准的所有记录。 调用 IDATABASE_GetRecordByID() 检索拥有给定 ID 的记录。
  5. 访问结束后，调用 IDATABASE_Release() 关闭数据库。

要包含的头文件列表

需要以下头文件：

AEEDB.h

函数列表

此接口的函数包括：

IDATABASE_AddRef()

IDATABASE_CreateRecord()

IDATABASE_GetNextRecord()

IDATABASE_GetRecordByID()

IDATABASE_GetRecordCount()

IDATABASE_Release()

IDATABASE_Reset()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDATABASE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDATABASE_Release()

返回函数列表

IDATABASE_CreateRecord()

说明：

此函数用于创建新的数据库记录，其字段由 pIDatabase 所指定数据库的 pDBFields
指定。

原型：

IDBRecord * IDATABASE_CreateRecord
(
IDatabase * pIDatabase,
AEEDBField * pDBFields,
int iNumfields
)

参数：

pIDatabase | 指向创建记录的 IDatabase 接口对象的指针。
pDBFields | 指向需放在此函数创建的新记录中的数据库字段的指针。
iNumFields | 记录中的字段数。

返回值：

如果成功，将返回指向创建的数据库记录的指针。

如果失败，将返回 NULL。

备注：

数据库中将添加一条新记录。 在释放数据库之前，必须使用 IDBRECORD_Release() 释放 IDBRecord。 如果未释放记录，IDATABASE_Release() 将无法关闭数据库。

另请参阅：

AEEDBField

返回函数列表

IDATABASE_GetNextRecord()

说明：

此函数用于返回数据库的下一条 IDBRecord。

原型：

IDBRecord * IDATABASE_GetNextRecord(IDatabase * pIDatabase)

参数：

pIDatabase
指向 IDatabase 接口对象的指针，该对象的下一个记录即为是所请求的记录。

返回值：

如果成功，将返回指向数据库记录的指针。

否则，将返回 NULL。

备注：

在释放数据库之前，必须使用 IDBRECORD_Release() 释放 IDBRecord。 如果未释放记录，IDATABASE_Release() 将无法关闭数据库。

另请参阅：

无

返回函数列表

IDATABASE_GetRecordByID()

说明：

此函数用于返回一个拥有指定 ID 的记录的指针。

原型：

IDBRecord * IDATABASE_GetRecordByID
(
IDatabase * pIDatabase,
uint16 u16RecID
)

参数：

pIDatabase | 指向 IDatabase 接口对象的指针，该对象的记录即为所请求的记录。
u16RecID | 记录的指针。

返回值：

如果成功，指向拥有指定指针的数据库记录的指针。

如果失败，将返回 NULL。

备注：

在释放数据库之前，必须使用 IDBRECORD_Release() 释放 IDBRecord。 如果未释放记录，IDATABASE_Release() 将无法关闭数据库。

另请参阅：

无

返回函数列表

IDATABASE_GetRecordCount()

说明：

此函数用于返回 pIDatabase 指定的数据库中的记录数。

原型：

uint32 IDATABASE_GetRecordCount(IDatabase * pIDatabase)

参数：

pIDatabase
指向 IDatabase 接口对象的指针，该对象的记录数即为所请求的计数。

返回值：

如果成功，将返回数据库中的记录数。

如果 pIDatabase 指向具有无效数据库句柄的 IDatabase 接口对象，则返回 0（零）。

备注：

无

另请参阅：

无

返回函数列表

IDATABASE_Release()

说明：

此函数用于减少 IDatabase 接口对象的引用计数。 如果引用计数为 0（零），此函数将关闭数据库。

原型：

uint32 IDATABASE_Release(IDatabase * pIDatabase)

参数：

pIDatabase
指向需要减少其引用计数的 IDatabase 接口对象的指针。

返回值：

已减少的对象引用计数。

如果该对象已被释放，且不再有效，则返回 0（零）。

备注：

在关闭数据库之前，必须使用 IDBRECORD_Release() 释放数据库的所有记录。 如果未释放记录，此函数将无法关闭数据库。

另请参阅：

IDATABASE_AddRef()

IDBRECORD_Release()

IDBMGR_OpenDatabase()

IDBMGR_OpenDatabaseEx()

返回函数列表

IDATABASE_Reset()

说明：

此函数用于清除 pIDatabase 指定的数据库的记录指针。

原型：

void IDATABASE_Reset(IDatabase * pIDatabase)

参数：

pIDatabase
指向需清除记录指针的 IDatabase 接口对象的指针。

返回值：

无

备注：

在此函数获取数据库的第一个记录之后，调用 IDATABASE_GetNextRecord()。

另请参阅：

无

返回函数列表


IDateCtl 接口

日期控件用在需要设备用户选择日期的接口中。 日期控件有两类（创建日期控件实例时，可以指定 ClassID 选择需要的类型）：

  • 标准日期控件 (ClassID AEECLSID_DATECTL) 允许设备用户使用上下左右键选择指定的月、日和年。
  • 日期选择控件 (ClassID AEECLSID_DATEPICKCTL) 显示一个月历，用户可以用箭头键选择月份中的任意一天，或滚动到下月或上月。

IDATECTL_HandleEvent() 用于处理 AVK_SELECT、AVK_UP、AVK_DOWN、AVK_LEFT 和 AVK_RIGHT 密钥。 当函数收到 AVK_SELECT 时，如果已启用命令发送（参阅本节后面的部分），日期控件将发出 EVT_COMMAND 信号通知应用程序设备用户已经选择日期；然后用一个 IDateCtl 函数获取所选的日期值。 对于标准日期控件，如果设备用户按下 AVK_LEFT 选择月或 AVK_RIGHT 选择年时将发送控件切换事件 (EVT_CTL_TAB)。 使用这些事件可以使设备用户在多控件屏幕上定位控件（对话框处理 EVT_CTL_TAB 事件并在需要时改变控件焦点）。

目前，日期控件没有特定的属性，所以不使用函数 IDATECTL_SetProperties() 和 IDATECTL_GetProperties()。

除了 IControl 接口的函数之外，IDateCtl 接口还执行若干其它函数。

  • IDATECTL_SetTitle() 用于指定显示在日期控件上方的标题。
  • IDATECTL_SetDate() 将保存在控件中的日期设置为函数整数月、星期值和日期参数中指定的值。
  • IDATECTL_GetDate() 可以用相同格式获取控件的当前日期。
  • IDATECTL_SetJulianDay() 和 IDATECTL_GetJulianDay() 类似，除了以 1970 年 1 月 1 日前第一个星期日后的天数来设置和获取控件日期。
  • IDATECTL_GetDayOfWeek() 返回控件当前日期对应的星期值。
  • 函数 IDATECTL_GetDateString()、IDATECTL_GetDayString() 和 IDATECTL_GetMonthString() 可以将日期控件的当前日期、星期值或月值保存为字符串。 日期字符串有若干种格式可以选择（如，指定日期、月和年的顺序，以及使用完整的月份名称还是三个字母的缩写）。
  • 对于日期选择控件，IDATECTL_SetActiveDayMask() 可以使月份当中指定的天数在日期选择日历显示区反白显示，这一点可用来指定假期等特殊日期。该函数由指定月份中哪些天以这种方式显示的 32 位参数调用。
  • 当日期控件处于激活状态并且设备用户按下 AVK_SELECT 键后，IDATECTL_EnableCommand() 允许禁用或启用发送命令（默认情况下禁用命令发送）。 该函数也可使您指定命令 ID（例如，调用应用程序的 IAPPLET_HandleEvent() 函数时与 EVT_COMMAND 一同发送的 wParam 值）。

使用日期控件

  1. 调用 ISHELL_CreateInstance() 创建一个日期控件的实例，指定标准或日期选择日期控件的 ClassID。
  2. 调用 IDATECTL_SetRect() 指定包含该控件的屏幕矩形。
  3. 如果必要，调用 IDATECTL_SetDate() 或 IDATECTL_SetJulianDay() 指定控件的初始日期值（如不指定，控件的日期字段最初将显示为空白）。
  4. 调用 IDATECTL_SetActive() 激活控件，使其可以接收设备用户选择日期值时生成的按键事件。 当控件处于激活状态时，应用程序必须使用 IDATECTL_HandleEvent() 将这些事件发送给控件。
  5. 设备用户选择日期后，调用上述一个日期获取函数以特定的格式访问其值。 设备用户的日期选择可以通过 EVT_COMMAND 事件（如果启用命令发送），或通过设备用户退出包含日期控件的屏幕来通知。
  6. 不再需要日期控件时，调用 IDATECTL_Release() 将其释放。

要包含的头文件列表

需要以下头文件：

AEEDate.h

函数列表

此接口的函数包括：

IDATECTL_AddRef()

IDATECTL_EnableCommand()

IDATECTL_GetDate()

IDATECTL_GetDateString()

IDATECTL_GetDayOfWeek()

IDATECTL_GetDayString()

IDATECTL_GetFont()

IDATECTL_GetJulianDay()

IDATECTL_GetMonthString()

IDATECTL_GetProperties()

IDATECTL_GetRect()

IDATECTL_HandleEvent()

IDATECTL_IsActive()

IDATECTL_Redraw()

IDATECTL_Release()

IDATECTL_Reset()

IDATECTL_SetActive()

IDATECTL_SetActiveDayMask()

IDATECTL_SetDate()

IDATECTL_SetFont()

IDATECTL_SetJulianDay()

IDATECTL_SetProperties()

IDATECTL_SetRect()

IDATECTL_SetTitle()

IDATECTL_SizeToFit()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDATECTL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表

IDATECTL_Release()

返回函数列表

IDATECTL_EnableCommand()

说明：

此函数用于启用日期控件对象以便向激活的小程序发送用户定义的命令。 如果 bEnable 为 TRUE，则日期控件对象在收到按下选择键生成的事件后，会将 nCmdId 作为 EVT_COMMAND 向激活的小程序发送。 该事件的处理是小程序特定的，并由用户定义。

原型：

void IDATECTL_EnableCommand
(
IDateCtl * pIDateCtl,
boolean bEnable,
uint16 nCmdId
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
bEnable | 启用标记的布尔值。
nCmdId | 命令 ID。

返回值：

无

备注：

此函数可用于从日期控件对象向激活的小程序发送用户定义的命令。

另请参阅：

无

返回函数列表

IDATECTL_GetDate()

说明：

此函数用于获取日期控件对象的日期。

原型：

boolean IDATECTL_GetDate
(
IDateCtl * pIDateCtl,
unsigned int * pnYear,
unsigned int * pnMonth,
unsigned int * pnDay
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
pnYear | 年份 [YYYY] 占位符，如 2000。
pnMonth | 月份 [MM] 占位符，如 12。
pnDay | 日期 [DD] 占位符，如 31。

返回值：

如果成功，将返回 TRUE。

如果失败，将返回 FALSE。

备注：

无

另请参阅：

IDATECTL_SetDate()

返回函数列表

IDATECTL_GetDateString()

说明：

此函数用于获得指定格式的日期字符串。

原型：

boolean IDATECTL_GetDateString
(
IDateCtl * pIDateCtl,
AECHAR * pBuffer,
unsigned int nMaxSize,
unsigned int * pnChars,
uint32 dwDateFormat
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。 |
pBuffer | 日期字符串的占位符。 |
nMaxSize | 缓冲区中要读取的最大字符数。 |
pnChars | 写入 pBuffer 的字符数占位符。 |
dwDateFormat | 日期字符串的格式。 请使用下面一种日期字符串格式： |
 | DFMT_DD_MONTH_YYYY | 18 July 2000
 | DFMT_DD_MON_YYYY | 18 Jul 2000
 | DFMT_DD_MON_YY | 18 Jul '00
 | DFMT_MONTH_DD_YYYY | July 18, 2000
 | DFMT_MON_DD_YYYY | Jul. 18, 2000
 | DFMT_MON_DD_YY | Jul 18, 00
 | DFMT_MM_DD_YYYY | 10/15/2000
 | DFMT_DD_MM_YYYY | 15/10/2001
 | DFMT_YYYY_MM_DD | 2001/6/1
 | DFMT_INT_YYYY_MM_DD | 2001.06.01

返回值：

如果成功，将返回 TRUE。

如果失败，将返回 FALSE。

备注：

只能为参数 dwDateFormat 选用一种日期字符串格式。

另请参阅：

IDATECTL_GetDayString()

IDATECTL_GetMonthString()

返回函数列表

IDATECTL_GetDayOfWeek()

说明：

此函数用于获取日期控件对象的星期值。

原型：

uint16 IDATECTL_GetDayOfWeek(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

返回值：

下列之一：

DOW_SUNDAY

DOW_MONDAY

DOW_TUESDAY

DOW_WEDNESDAY

DOW_THURSDAY

DOW_FRIDAY

DOW_SATURDAY

备注：

无

另请参阅：

无

返回函数列表

IDATECTL_GetDayString()

说明：

此函数用于获取与日期控件对象当前日期相对应的星期名称。

原型：

AECHAR * IDATECTL_GetDayString
(
IDateCtl * pIDateCtl,
AECHAR * pBuffer,
unsigned int nMaxSize,
unsigned int * pnChars
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
pBuffer | 星期名称占位符。
nMaxSize | 缓冲区的大小。
pnChars | 写入 pBuffer 的字符数占位符。

返回值：

如果成功，将返回指向 pBuffer 中星期串末尾的指针。

如果失败，将返回 NULL。

备注：

无

另请参阅：

IDATECTL_GetMonthString()

IDATECTL_GetDateString()

返回函数列表

IDATECTL_GetFont()

说明：

此方法允许调用程序获取标题和文本字体。

原型：

boolean IDATECTL_GetFont
(
IDateCtl * pIDateCtl,
AEEFont *pfntText,
AEEFont *pfntTitle
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针
pfntText | 指向设置文本字体位置的指针
pfntTitle | 指向设置标题字体位置的指针

IDisplay 发生以下更改：

  • 1) IDisplay 多个实例：
    对于 BREW 2.0，IDisplay 支持多个实例。 这意味着每次使用 AEECLSID_DISPLAY 调用 ISHELL_CreateInstance()，都将返回一个应用程序全局 IDisplay 实例。该实例可以维护状态信息，如字体、颜色、目标位图和剪切矩形（新增）等。 而且，可以复制 IDisplay 实例并进行修改，使得小程序的不同部分均由单独的 IDisplay 实例进行绘制，从而避免每次绘制操作后都需要恢复状态数据。 为支持此功能，IDisplay 接口中添加了 IDISPLAY_Clone()。 此外，还添加了新的 ClassID （AEECLSID_DISPLAYCLONE），以生成当前应用程序全局 IDisplay 的副本。
  • 2) IDisplay 剪切矩形：添加
    IDISPLAY_SetClipRect() 可设置限制所有 IDisplay 绘制函数的剪切矩形。 要将剪切矩形重置为整个屏幕，请在 (AEERect*) 参数中传递 NULL。

返回值：

如果成功，将返回 TRUE。

如果失败，将返回 FALSE。

备注：

无

另请参阅：

IDATECTL_SetFont()

返回函数列表

IDATECTL_GetJulianDay()

说明：

此函数用于获取指定日期控件对象的儒略（阳历）日值。

原型：

int32 IDATECTL_GetJulianDay(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

返回值：

日期控件对象的儒略日值

备注：

无

另请参阅：

IDATECTL_SetJulianDay()

返回函数列表

IDATECTL_GetMonthString()

说明：

此函数用于获取日期控件对象当前日期的月份名称。

原型：

AECHAR * IDATECTL_GetMonthString
(
IDateCtl * pIDateCtl,
AECHAR * pBuffer,
unsigned int nMaxSize,
unsigned int * pnChars
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
pBuffer | 月份名称的占位符。
nMaxSize | 缓冲区的大小。
pnChars | 写入 pBuffer 的字符数占位符。

返回值：

如果成功，将返回指向 pBuffer 中月份名称串末尾的指针。

如果失败，将返回 NULL。

备注：

无

另请参阅：

IDATECTL_GetDayString()

IDATECTL_GetDateString()

返回函数列表

IDATECTL_GetProperties()

说明：

此函数用于返回日期控件特定属性或标记。 目前没有日期控件特定属性，此函数将总是返回 0（零）。

原型：

uint32 IDATECTL_GetProperties(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

返回值：

所有情况下均返回 0（零）。

备注：

无

另请参阅：

IDATECTL_SetProperties()

返回函数列表

IDATECTL_GetRect()

说明：

此函数为指向 AEERect 结构的给定指针填入日期控件对象当前绑定矩形的坐标。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

原型：

void IDATECTL_GetRect(IDateCtl * pIDateCtl, AEERect * prc)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
prc | 要填入日期控件对象坐标的矩形。

返回值：

无

备注：

无

另请参阅：

AEERect

IDATECTL_SetRect()

返回函数列表

IDATECTL_HandleEvent()

说明：

此函数用于处理日期控件对象收到的事件。 日期控件对象仅在激活状态下处理接收到的事件。 日期控件对象处理的是按“上、下、左、右”键事件。 如果启用了命令发送，日期控件对象在收到按“选择”键生成的事件后，会将 IDATECTL_EnableCommand 函数指定的命令作为命令事件发送给激活的小程序。

原型：

boolean IDATECTL_HandleEvent
(
IDateCtl * pIDateCtl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
evt | 事件代码。
wp | [AVK_UP|AVK_DOWN|AVK_LEFT|AVK_RIGHT|AVK_SELECT
dwp | 与 wp 指定的按键类型对应的按键符号字符串。

返回值：

如果日期控件已处理该事件，将返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

IDATECTL_EnableCommand()

返回函数列表

IDATECTL_IsActive()

说明：

此函数用于返回日期控件对象是否处于激活状态。 返回值 TRUE 表示处于激活状态，而返回值 FALSE 表示处于未激活状态。

原型：

boolean IDATECTL_IsActive(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

返回值：

如果日期控件处于激活状态，将返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

IDATECTL_SetActive()

返回函数列表

IDATECTL_Redraw()

说明：

此函数用于指示日期控件对象刷新其内容。 日期控件对象并非在每次更改日期控件底层数据时都刷新内容。 目的是在更新若干数据时，使屏幕闪烁降至最低。

原型：

boolean IDATECTL_Redraw(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

返回值：

如果已刷新日期控件，将返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IDATECTL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表

IDATECTL_AddRef()

返回函数列表

IDATECTL_Reset()

说明：

此函数用于指示日期控件清除（释放或删除）其内容，并立即离开激活或焦点模式。

原型：

void IDATECTL_Reset(IDateCtl * pIDateCtl)

参数：

pIDateCtl
指向 IDateCtl 接口对象的指针。

1

返回值：

无

备注：

此函数可使控件处于非激活状态。 未激活的控件不处理向它发送的事件。

另请参阅：

IDATECTL_SetActive()

返回函数列表

IDATECTL_SetActive()

说明：

此函数用于激活日期控件对象。 只有激活的日期控件对象才能处理向它发送的事件。 未激活的日期控件对象将忽略这些事件。

原型：

void IDATECTL_SetActive(IDateCtl * pIDateCtl, boolean bActive)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
bActive | 指定激活 (TRUE) 或停用 (FALSE) 日期控件的布尔标记

返回值：

无

备注：

无

另请参阅：

IDATECTL_IsActive()

返回函数列表

IDATECTL_SetActiveDayMask()

说明：

此函数用于设置一个新的激活日掩码。 激活日掩码是一个 32 位整数，其中每个
0（零）到 30 位可指定某一日的激活状态。 设置了对应位的激活日在左上角绘有一个
点 (.)。

原型：

void IDATECTL_SetActiveDayMask(IDateCtl * pIDateCtl, uint32 dwMask)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
dwMask | 新的激活日掩码。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDATECTL_SetDate()

说明：

此函数用于向日期控件对象分配指定的日期。

原型：

boolean IDATECTL_SetDate
(
IDateCtl * pIDateCtl,
unsigned int nYear,
unsigned int nMonth,
unsigned int nDay
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
nYear | 年 [YYYY]，如 2000。
nMonth | 月 [MM]，如 12。
nDay | 日 [DD]，如 31。

返回值：

如果成功，将返回 TRUE。

如果失败，将返回 FALSE。

备注：

最小错误检查： 1 到 31 号之间的任何一天以及 1 到 12 月当中的任何一月都有效。
输入 4/31/98 会变为 5/1/98。

另请参阅：

IDATECTL_GetDate()

返回函数列表

IDATECTL_SetFont()

说明：

此方法允许调用程序设置标题和文本字体。

原型：

void IDATECTL_SetFont
(
IDateCtl * pIDateCtl,
AEEFont fntText,
AEEFont fntTitle
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针
fntText | 文本使用的字体
fntTitle | 标题使用的字体

返回值：

无

备注：

无

另请参阅：

IDATECTL_GetFont()

返回函数列表

IDATECTL_SetJulianDay()

说明：

此函数用于向日期控件对象分配指定的儒略日。

原型：

boolean IDATECTL_SetJulianDay(IDateCtl * pIDateCtl, int32 lJulDate)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
lJulDate | 要分配的儒略日。

返回值：

如果儒略日输入有效，将返回 TRUE。

如果儒略日输入无效，将返回 FALSE。

备注：

无

另请参阅：

IDATECTL_GetJulianDay()

返回函数列表

IDATECTL_SetProperties()

说明：

此函数用于设置日期控件特定属性或标记。 属性掩码的低 8 位可以指定控件的日期
格式。 默认情况下为 DFMT_DD_MON_YY。

原型：

void IDATECTL_SetProperties(IDateCtl * pIDateCtl, uint32 dwProps)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
dwProps | 32 位标记或属性组。

返回值：

无

备注：

无

另请参阅：

IDATECTL_GetProperties()

返回函数列表

IDATECTL_SetRect()

说明：

此函数用于将指定的矩形设置为日期控件对象的绑定矩形。 如果日期控件对象位于月份视图，则指定的矩形还用于确定绘制日期的网格。

原型：

void IDATECTL_SetRect(IDateCtl * pIDateCtl, const AEERect * prc)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
prc | 日期控件对象的绑定矩形。

返回值：

无

备注：

默认情况下，将整个设备屏幕设置为日期控件对象的绑定矩形。

另请参阅：

AEERect

IDATECTL_GetRect()

返回函数列表

IDATECTL_SetTitle()

说明：

此函数用于设置日期控件对象的标题。 如果 pText 为非 NULL，函数会将 pText 指定的字符串设置为日期控件对象的标题。 如果 pText 为 NULL，函数将从资源文件读取与给定资源标识符对应的标题字符串，并将其设置为日期控件对象的标题。

原型：

boolean IDATECTL_SetTitle
(
IDateCtl * pIDateCtl,
const char * pszResFile,
uint16 wResID,
AECHAR * pText
)

参数：

pIDateCtl | 指向 IDateCtl 接口对象的指针。
pszResFile | 以 NULL 结尾，包含资源文件名的字符串。
wResID | 字符串资源标识符。
pText | 以 NULL 结尾的标题字符串。

返回值：

如果成功，将返回 TRUE。

如果失败，将返回 FALSE。

备注：

无

副作用：

如果 pText 为 NULL，并且 pszResFile 和 wResID 有效，此函数则将日期控件对象标题字符串分配给 pText。

另请参阅：

无

返回函数列表

IDATECTL_SizeToFit()

说明：

此方法允许调用程序将矩形调整为日期文本大小。

原型：

void IDATECTL_SizeToFit(IDateCtl * pIDateCtl, AEERect *prc);

参数：

pIDateCtl | 指向 ITimeCtl 接口对象的指针
prc | 指向设置绑订矩形位置的指针

返回值：

无

备注：

此方法仅用于 AEECLSID_DATECTL，对 AEECLSID_DATEPICKCTL 无效。

另请参阅：

AEERect

返回函数列表


IDBMgr 接口

IDBMgr 接口函数用于创建、打开和删除收集了多字段记录的数据库。 打开数据库后，您可以使用 IDatabase 接口中的函数创建和检索数据库记录以及关闭数据库，并且，您还可以使用 IDBRecord 接口中的函数访问和更新个别记录的字段。

注意：应用程序必须具有 PL_FILE 或 PL_SYSTEM 优先级，才能调用此接口中用于创建或删除数据库的函数。

IDBMGR_OpenDatabase() 用于打开具有指定名称的现有数据库，该名称对应于包含数据库内容的 BREW 文件名。 调用此函数时，如果数据库尚不存在，则需先创建数据库。IDBMGR_OpenDatabaseEx() 也一样，但在创建新数据库时，它还允许您指定最小记录容量和最小记录数；该函数将保留足够的内存，用于保存指定数量的记录。 这两个函数都会返回一个指向 IDatabase 接口实例的指针，该指针可以用来访问打开的数据库。IDBMGR_Remove() 可以通过删除保存其内容的文件来删除数据库。 如果数据库已经打开，则必须先调用 IDBMGR_Release() 将其关闭，然后删除数据库。

要使用 IDBMgr 接口中的函数，请执行以下操作

  1. 调用 ISHELL_CreateInstance() 创建 IDBMgr 接口实例。
  2. 调用 IDBMGR_OpenDatabase() 打开一个现有数据库或创建一个新数据库。 如果需要为新创建的数据库指定最小容量，请使用 IDBMGR_OpenDatabaseEx()。
  3. 使用步骤 2 中获取的 IDatabase 接口指针调用 IDatabase 接口中的函数，以创建和检索数据库中的记录。 使用 IDBRecord 接口 函数访问和修改数据库记录的字段。
  4. 访问结束后，调用 IDATABASE_Release() 关闭数据库。
  5. 如有必要，调用 IDBMGR_Remove() 删除数据库。
  6. 不再需要 IDBMgr 接口实例时，调用 IDBMGR_Release()。

要包含的头文件列表

需要以下头文件：

AEEDB.h

函数列表

此接口的函数包括：

IDBMGR_AddRef()

IDBMGR_OpenDatabase()

IDBMGR_OpenDatabaseEx()

IDBMGR_Release()

IDBMGR_Remove()

IDBMGR_SetCacheSize()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDBMGR_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDBMGR_Release()

返回函数列表

IDBMGR_OpenDatabase()

说明：

此函数用于打开指定的数据库。 如果数据库已经打开，则返回 NULL。 如果数据库不存在，布尔标记 bCreate 将指定要执行的操作。 如果指定的数据库不存在，并且 bCreate 为 TRUE，则此函数将创建一个新数据库，其最小记录数和最小记录容量参数均设置为 0（零）。

原型：

IDatabase * IDBMgr_OpenDatabase
(
IDBMgr * pIDBMgr,
const char * pszFile,
boolean bCreate
)

参数：

pIDBMgr | 指向 IDBMgr 接口对象的指针。
pszFile | 以 NULL 结尾的字符串，表示数据库文件名。
bCreate | 指定未找到数据库时是否必须创建数据库。 只有在此标记设置为 TRUE 时才创建数据库。

返回值：

如果成功，将返回指向 IDatabase 对象的指针。

如果失败，将返回 NULL。

备注

使用 IDATABASE_Release() 关闭数据库。

另请参阅：

无

返回函数列表

IDBMGR_OpenDatabaseEx()

说明：

此函数用于打开指定的数据库。 如果数据库已经打开，则返回 NULL。 如果数据库不存在，布尔标记 bCreate 将指定要执行的操作。 如果指定的数据库不存在，并且 bCreate 为 TRUE，则此函数将创建一个新数据库。 创建数据库时，最小记录容量可由 dwMinSize 指定，最小记录数则可由 wMinRecs 指定。

原型：

IDatabase * IDBMgr_OpenDatabaseEx
(
IDBMgr * pIDBMgr,
const char * pszFile,
boolean bCreate,
uint32 dwMinSize,
uint16 wMinRecs
)

参数：

pIDBMgr | 指向 IDBMgr 接口对象的指针。
pszFile | 以 NULL 结尾的字符串，表示数据库文件名。
bCreate | 指定未找到数据库时是否必须创建数据库。 只有在此标记设置为 TRUE 时才创建数据库。
dwMinSize | 数据库记录的最小容量。
wMinRecs | 数据库可保存的最小记录数。

返回值：

如果成功，将返回指向 IDatabase 对象的指针。

如果失败，将返回 NULL。

备注：

使用 IDATABASE_Release() 关闭数据库。

另请参阅：

无

返回函数列表

IDBMGR_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表

IDBMGR_AddRef()

返回函数列表

IDBMGR_Remove()

说明：

此函数用于删除指定的数据库。

原型：

int IDBMgr_Remove(IDBMgr * pIDBMgr, const char * pszFile)

参数：

pIDBMgr | 指向 IDBMgr 接口对象的 IDBMgr * 指针。
pszFile | 以 NULL 结尾的字符串，指定要删除数据库的名称。

返回值：

如果成功删除数据库，则返回 SUCCESS。

如果找不到数据库文件，将返回 EBADFILENAME。

备注：

在使用 IDBMGR_Remove() 删除数据库之前，应使用 IDATABASE_Release() 将其关闭。 删除数据库后，对应的数据库文件也被删除。 随后便无法打开或访问已删除的数据库。

另请参阅：

无

返回函数列表

IDBMGR_SetCacheSize()

说明：

此函数用于设置对数据库的文件缓存操作大小。它允许调用程序有选择地缓冲文件访问，以提高性能。 此函数必须在调用 IDBMGR_OpenDatabase() 之前调用。

原型：

void IDBMGR_SetCacheSize(IDBMgr * pIDBMgr, int32 nSize)

参数：

pIDBMgr
指向 IDBMgr 对象的指针
nSize
缓存的大小。
  • SCS_DEFAULT - 使用由 OEM 指定的默认缓存文件大小

返回值：

无

备注：

此功能的可用性依赖于基本数据库实现，某些设备可能不支持此功能。

另请参阅：

无

返回函数列表


IDBRecord 接口

IDBRecord 接口包含一组用于访问和更新数据库记录字段的函数。 您可以使用
IDatabase 接口中的函数获取特定记录的 IDBRecord 接口实例。 创建新记录时，IDATABASE_CreateRecord() 将返回 IDBRecord 接口指针，在从数据库检索现有记录时，IDATABASE_GetNextRecord() 和 IDATABASE_GetRecordByID() 也将返回该指针。 获取某个记录的 IDBRecord 接口指针后，就可以按照本节后面说明的操作，使用该指针来访问记录字段。 完成数据库记录访问之后，调用 IDBRECORD_Release() 关闭数据库记录。

注意：应用程序必须具有 PL_FILE 或 PL_SYSTEM 优先级，才能调用该接口中用于修改数据库内容的函数。

每个记录字段均包含记录名称、数据类型、指向记录内容的指针以及内容的长度。 IDBRecord 接口中的记录访问函数可以操作记录的当前字段。IDBRECORD_Reset() 将记录的第一个字段作为当前字段，IDBRECORD_NextField() 则将当前字段推进为记录的下一个字段。IDBRECORD_NextField() 还可以返回新的当前字段的名称、数据类型和长度（但不是内容），或者当枚举完所有的记录字段后返回记录结束指示。IDBRECORD_GetField() 返回指向当前字段内容的指针，以及字段的名称、数据类型和长度。

在内容的数据类型已知的情况下，IDBRecord 接口可以提供一些更简单的函数，用于访问字段内容：

  • IDBRECORD_GetFieldWord() 用于在字段类型为字时，检索当前字段的内容。
  • IDBRECORD_GetFieldWord() 用于在字段类型为双字时，检索当前字段的内容。
  • IDBRECORD_GetFieldString() 用于在字段类型为字符串时，
    检索当前字段的内容。

如果当前字段的内容不具有相应类型，则这些函数中都将返回失败指示。

要修改记录字段，请使用 IDBRECORD_Update()。 此函数接受的输入与 IDATABASE_CreateRecord() 相同： 提供一个指向 AEEDBField 结构数组的指针，该数组包含记录中每个字段的名称、类型、内容和长度的新值，以及数组中的字段数。 要更新记录中的单个字段，必须为记录的所有字段指定值。

IDBRECORD_GetID() 用于返回记录的唯一标识符。 调用 IDATABASE_GetRecordByID() 检索记录时，可以使用记录 ID。IDBRECORD_Remove() 可以从数据库中删除记录。

使用 IDBRecord 接口中的函数

  1. 如有必要，调用 ISHELL_CreateInstance() 获取 IDBMgr 接口的实例。
  2. 调用 IDBMGR_OpenDatabase() 或 IDBMGR_OpenDatabaseEx() 获取一个指向新的或现有数据库的 IDatabase 接口指针。
  3. 调用 IDATABASE_CreateRecord(), IDATABASE_GetRecordByID() 或 IDATABASE_GetNextRecord() 获取要访问记录的 IDBRecord 接口指针。

根据需要访问记录

  1. 调用 IDBRECORD_Reset() 和 IDBRECORD_NextField() 逐一访问记录字段，
    并获取每个字段的名称、数据类型和长度。 要访问当前字段的内容，请使用上述 IDBRECORD_GetField() 函数之一。
  2. 调用 IDBRECORD_GetID() 获取记录唯一的 ID。
  3. 调用 IDBRECORD_Update() 为记录的所有字段提供新值。
  4. 调用 IDBRECORD_Remove() 从数据库中删除记录。
  5. 结束记录访问后，调用 IDBRECORD_Release() 关闭记录（如果在步骤 4 中已经删除了该记录，这时就无需释放）。

要包含的头文件列表

需要以下头文件：

AEEDB.h

函数列表

此接口的函数包括：

IDBRECORD_AddRef()

IDBRECORD_GetField()

IDBRECORD_GetFieldDWord()

IDBRECORD_GetFieldString()

IDBRECORD_GetFieldWord()

IDBRECORD_GetID()

IDBRECORD_NextField()

IDBRECORD_Release()

IDBRECORD_Remove()

IDBRECORD_Reset()

IDBRECORD_Update()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDBRECORD_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDBRECORD_Release()

返回函数列表

IDBRECORD_GetField()

说明：

此函数用于返回当前字段的原始数据、类型、名称和长度。 返回的数据不包括数据头，返回的长度是数据的长度。

原型：

byte * IDBRECORD_GetField
(
IDBRecord * pIDBRecord,
AEEDBFieldName * pName,
AEEDBFieldType * pDBFieldType,
uint16 * pnLen
)

参数：

pIDBRecord | [in] | 指向 IDBRecord 接口对象的指针，该对象的字段即为所请求的字段。
pName | [out] | 指向字段名的指针。
pDBFieldType | [out] | 指向字段类型的指针。
pnLen | [out] | 指向字段长度（以字节为单位）的指针。

返回值：

如果成功，将返回指向包含所请求字段的缓冲区的指针。

如果失败，将返回 NULL。

备注：

以下举例说明此函数的用途。 如果数据库记录中的字段对应于 AEEDBFIELD_LASTNAME，并且包含姓氏 "Smith" 的 AECHAR 字符串 wStr，则此函数返回指向包含 AECHAR 字符串 "Smith" 的字节缓冲区的指针。 如下填写参数：

* pName = AEEDBFIELD_LASTNAME
* pDBFieldType = AEEDB_FT_STRING
* pDBFieldLen = WStrlen(wStr) * sizeof(AECHAR) = 6 * 2 = 12（以 0 结尾）

另请参阅：

AEEDBFieldType

AEEDBFieldName

返回函数列表

IDBRECORD_GetFieldDWord()

说明：

此函数用于对指定的数据库记录执行 IDBRECORD_GetField() 操作，并检查返回的字段类型。 如果字段类型为 AEE_FT_DWORD，此函数会将 pdwRet 设置成指向包含
双字的缓冲区。

原型：

boolean IDBRECORD_GetFieldDWord
(
IDBRecord * pIDBRecord,
dword * pdwRet
)

参数：

pIDBRecord | 指向 IDBRecord 接口对象的指针，该对象的字段即为所请求的字段。
pdwRet | 指向此函数所返回双字的指针。

返回值：

如果字段类型为 AEE_FT_DWORD，将返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_GetFieldString()

说明：

此函数用于为该类型字段返回 AECHAR * 字符串。

原型：

AECHAR * IDBRECORD_GetFieldString(IDBRecord * pIDBRecord)

参数：

pIDBRecord
指向 IDBRecord 接口对象的指针，该对象的字段即为所请求的字段。

返回值：

如果成功，将返回指向包含所请求字段的字符串的指针。

如果失败，将返回 NULL。

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_GetFieldWord()

说明：

此函数用于对指定的数据库记录执行 IDBRECORD_GetField() 操作，并检查返回的字段类型。 如果字段类型为 AEE_FT_WORD，此函数会将 pwRet 设置为指向包含该字的缓冲区。

原型：

boolean IDBRECORD_GetFieldWord(IDBRecord * pIDBRecord, word * pwRet)

参数：

pIDBRecord | 指向 IDBRecord 接口对象的指针，该对象的字段即为所请求的字段。
pwRet | 指向此函数所返回字的指针。

返回值：

如果字段类型为 AEE_FT_WORD，将返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_GetID()

说明：

此函数用于获取指定记录的 ID。

原型：

uint16 IDBRECORD_GetID(IDBRecord * pIDBRecord)

参数：

pIDBRecord
指向 IDBRecord 接口对象的指针，该对象的 ID 即为所请求的 ID。

返回值：

如果成功，将返回指定记录的 ID。

如果失败，将返回 AEE_DB_ENULLREC。

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_NextField()

说明：

此函数用于将字段指针设置为指向记录中的下一个（如果当前位置为 -1，则为第一个）字段。 它可返回字段的类型、名称和数据长度。

原型：

AEEDBFieldType IDBRECORD_NextField
(
IDBRecord * pIDBRecord,
AEEDBFieldName * pName,
int16 * pnLen
)

参数：

pIDBRecord | 指向 IDBRecord 接口对象的指针，该对象的下一个字段即为所请求的字段。
pName | 指向下一个字段名称的指针。
pnLen | 指向下一个字段长度的指针。

返回值：

如果成功，将返回包含字段类型的结构，即 AEEDBFieldType。

如果失败，将返回 AEEDB_FT_NONE。

备注：

如果指定的或默认的字段指针指向最后一个字段，则返回无效的字段类型。

另请参阅：

AEEDBFieldName

AEEDBFieldType

返回函数列表

IDBRECORD_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDBRECORD_AddRef()

返回函数列表

IDBRECORD_Remove()

说明：

此函数用于从数据库中删除记录并释放 IDBRecord 对象。

原型：

int IDBRECORD_Remove(IDBRecord * pIDBRecord)

参数：

pIDBRecord
指向需删除 IDBRecord 的指针。

返回值：

如果成功删除数据库记录，将返回 SUCCESS。

如果要删除的记录处于错误状态，将返回 AEE_DB_EBADREC。

如果数据库处于错误状态，将返回 AEE_DB_EBADSTATE。

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_Reset()

说明：

此函数用于使 pIDBRecord 的第一个字段成为当前字段。

原型：

void IDBRECORD_Reset(IDBRecord * pIDBRecord)

参数：

pIDBRecord
指向需重置的 IDBRecord 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDBRECORD_Update()

说明：

此函数用于更新指定了一组新字段值的记录。

原型：

int IDBRECORD_Update
(
IDBRecord * pIDBRecord,
AEEDBField * pDBFields,
int iNumFields
)

参数：

pIDBRecord | 指向需更新的 IDBRecord 接口对象的指针。
pDBFields | 指向新的字段值集的指针。
iNumFields | 新集中的字段数。

返回值：

如果成功更新数据库记录，将返回 SUCCESS。

如果无足够内存来执行此操作，将返回 ENOMEMORY。

如果 pDBFields 为 NULL，将返回 AEE_DB_ENULLFIELD。

如果 iNumFields< 为 0，将返回 AEE_DB_EBADFIELDNUM。

备注：

无

另请参阅：

无

返回函数列表


IDialog 接口

IDialog 接口包含两个函数，它们在使用 IShell 接口函数创建的对话框上运行
（有关 IShell 对话框相关函数的详细信息，请参阅 IShell 接口说明）。

IDIALOG_GetControl() 用于获取构成对话框的日期、菜单、文本和时间控件的接口指针。
使用这些指针可以修改控件的属性和矩形，或检索设备用户在每个控件中输入或选择的数据。

IDIALOG_SetFocus() 用于指定多个控件中当前具有焦点的控件（此控件可接收设备用户的键盘输入）。 当设备用户按下左右箭头键时，多个控件将生成控件切换事件。 对话框使用这些控件切换事件使设备用户在控件之间定位。 IDIALOG_SetFocus() 可与不支持控件切换的控件（如“软键”菜单）配合使用，或指定最初具有焦点的控件。

使用 IDIALOG_GetControl() 和 IDIALOG_SetFocus()

  1. 使用 BREW 资源编辑器或在代码中填写所需的对话框数据结构来创建对话框
    控件。
  2. 调用 ISHELL_CreateDialog() 创建对话框并将其显示在屏幕上。
  3. 调用 ISHELL_GetActiveDialog() 获取指向步骤 2 中所创建对话框的 IDialog 接口指针（ISHELL_CreateDialog() 不返回此类指针）。
  4. 输入步骤 3 中获取的接口指针和在步骤 1 中创建控件时指定的控件 ID，调用 IDIALOG_GetControl() 访问对话框中的控件。创建对话框后，立即使用此函数自定义对话框控件的外观和属性。
  5. 当对话框处于激活状态时，如果需要，可以调用 IDIALOG_SetFocus() 使设备用户选择在哪个控件中选择或输入数据。 例如，如果对话框使用“软键”菜单，则提供一个菜单项使设备用户返回到上一个控件以更改输入的数据。
  6. 完成数据输入后，调用 IDIALOG_GetControl() 获取设备用户在每个控件中输入或选择的值。
  7. 调用 ISHELL_EndDialog() 终止对话框。

注意：BREW 的当前版本不支持对话框标题。

注意：在多控件对话框中，左右箭头键应在对话框控件列表中上下移动。 在 BREW 的当前版本中，左箭头键具备下移功能，右箭头键则不起作用。

要包含的头文件列表

需要以下头文件：

AEEShell.h

函数列表

此接口的函数包括：

IDIALOG_AddRef()

IDIALOG_GetControl()

IDIALOG_GetID()

IDIALOG_GetProperties()

IDIALOG_Redraw()

IDIALOG_Release()

IDIALOG_SetEventHandler()

IDIALOG_SetFocus()

IDIALOG_SetProperties()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDIALOG_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDIALOG_Release()

返回函数列表

IDIALOG_GetControl()

说明：

此函数用于检索与指定标识符相关联控件的 IControl 指针。

原型：

IControl * IDIALOG_GetControl(IDialog * pIDialog, int16 wID)

参数：

pIDialog | 指向 IDialog 接口对象的指针。
wID | 控件的 ID。

返回值：

如果成功，将返回 IControl 指针。

如果失败，将返回 NULL。

备注：

无

另请参阅：

ISHELL_CreateDialog()

IDIALOG_SetFocus()

返回函数列表

IDIALOG_GetID()

说明：

返回对话框的资源 ID。

原型：

uint16 IDIALOG_GetID(IDialog * pIDialog)

参数：

pIDialog
指向 IDialog 接口对象的指针

返回值：

对话框的 16 位资源 ID。

备注：

无

另请参阅：

ISHELL_CreateDialog()

IDIALOG_SetFocus()

返回函数列表

IDIALOG_GetProperties()

说明：

此函数用于返回对话框的当前属性

原型：

uint32 IDIALOG_GetProperties(IDialog * pIDialog);

参数：

pIDialog
指向 IDialog 对象的指针

返回值：

对话框的当前属性

备注：

无

另请参阅：

IDIALOG_SetProperties()

IDIALOG_SetEventHandler()

ISHELL_CreateDialog()

返回函数列表

IDIALOG_Redraw()

说明：

此方法用于刷新指定对话框框及其所有控件

原型：

void IDIALOG_Redraw(IDialog *pIDialog)

参数：

pIDialog： 指向 IDialog 对象的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDIALOG_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDIALOG_AddRef()

返回函数列表

IDIALOG_SetEventHandler()

说明：

此函数可为对话框设置或重置事件处理程序。 还可以为对话框发送给应用程序的应用程序事件或对话框未处理的事件选择备选事件回调。 如果此事件处理程序必须接收对话框未处理的所有事件，则必须使用 IDIALOG_SetProperties() 设置 DLG_HANDLE_ALL_EVENTS 属性。 如果已设置此属性，则使用 IDIALOG_SetEventHandler() 设置的事件处理程序将获得对话框未处理的所有事件。如果未设置此属性，则使用 IDIALOG_SetEventHandler() 注册的事件处理程序将只收到对话框发送的事件（EVT_DIALOG_END、EVT_COMMAND）。

对话框处于激活状态时，其中的事件传递链为：

  1. 将事件提供给对话框中的控件。
  2. 将事件发送到已注册的事件处理程序
    • 如果对话框未处理该事件，且
    • 如果已设置 DLG_HANDLE_ALL_EVENTS，且
    • 如果已注册事件处理程序。
  3. 将事件发送到当前应用程序
    • 如果此事件处理程序未处理此事件。

原型：

void IDIALOG_SetEventHandler
(
IDialog * pIDialog,
PFNAEEEVENT pfn,
void * pUser
)

参数：

pIDialog | 指向 IDialog 对象的指针
pfn | 指向事件回调的指针
pUser | 作为第一参数发送到事件处理程序的用户数据指针

返回值：

无

备注：

无

另请参阅：

PFNAEEEVENT

ISHELL_CreateDialog()

IDIALOG_SetFocus()

返回函数列表

IDIALOG_SetFocus()

说明：

此函数用于将激活的控件焦点设置给指定标识符所关联的控件。

原型：

int16 IDIALOG_SetFocus(IDialog * pIDialog, int16 wID)

参数：

pIDialog | 指向 IDialog 接口对象的指针。
wID | 控件的 ID。

返回值：

具有焦点的控件的标识符。

备注：

无

另请参阅：

ISHELL_CreateDialog()

返回函数列表

IDIALOG_SetProperties()

说明：

此函数用于设置对话框的属性。 支持的属性包括：

DLG_HANDLE_ALL_EVENTS：

  • 如果已设置此属性，则使用 IDIALOG_SetEventHandler() 设置的事件处理程序将获得对话框未处理的所有事件。
  • 如果未设置此属性，则使用 IDIALOG_SetEventHandler() 注册的事件处理程序仅接收对话框发出的事件（EVT_DIALOG_END、EVT_COMMAND）。

原型：

void IDIALOG_SetProperties(IDialog * pIDialog, uitn32 dwProps);

参数：

pIDialog | 指向 IDialog 对象的指针
dwProps | 对话框属性

返回值：

无

备注：

无

另请参阅：

IDIALOG_GetProperties()

IDIALOG_SetEventHandler()

ISHELL_CreateDialog()

返回函数列表


IDIB 接口

IDIB 是一种结构和也是一个接口。 IDIB 继承了 IBitmap 的全部成员函数，因此通过类型转换，IDIB 可用作 IBitmap。 IDIB_TO_IBITMAP 内联函数用于类型安全转换。 与其它 BREW 接口不同，IDIB 还包含公有数据成员。 这些数据成员可高效读取或修改图像数据。

通常，应用程序通过使用类 ID AEECLSID_DIB 调用 IBITMAP_QueryInterface() 来从 IBitmap 指针获取 IDIB 指针。 并非所有的 IBitmap 类都支持 IDIB。在不支持的情况下，QueryInterface 函数将返回错误代码。 如果成功，则返回 IDIB 指针，调用者在使用完该指针之后，必须将其释放。

位图由二维像素数组构成。 IDIB 包含指示像素在内存中所处位置，以及如何解释这些像素值的成员。


像素数组结构

pBmp、nPitch 和 nDepth 成员说明了像素数组中像素的位置和大小。 nPitch 字段指定从任意行开头到下一行开头之间的距离（以字节为单位）。 宽距通常由位图宽度、正在应用的填充、以及位图是自顶向下还是自底向上来决定。 自底向上位图的宽距值为负。

IDIB 用户应具有 nPitch 值，并且未设定位图的填充或方向。pBmp 参数指向保存 DIB 像素数据的内存缓冲区中的第一个扫描行（y=0）。 对于自顶向下的 DIB，该指针指向缓冲区像素数据的第一行。 对于自底向上的 DIB，该指针则指向缓冲区像素数据的最后一行。


用法示例：

对于颜色深度为 8（一字节每像素）、宽度为 9 和高度为 10 的位图，可能有以下表示
（仅其中一部分）：

nPitch | pBmp | 位数据组的起始
自顶向下的 BMP 文件 | 12 | 0
自底向上的 BMP 文件 | -12 | 96
自顶向下的紧缩位图 | 9 | 0
自底向上的紧缩位图 | - 9 | 72

实际上，在所有这些情况下读取任何 8 位 DIB 像素的代码都相同：

COLORVALUE = pdib->pBmp[ y * pdib->nPitch + x ]

对齐： 行通常开始于 32 位边界处，但只有两种情况下能够保证对齐。 当 nDepth 为 32 时，
各行应按 32 位对齐；当 nDepth 为 16 时，各行应在 16 位边界上对齐。

在一行内，最左 (x=0) 像素开始于对应字节的最高有效位。 如果需要，可以按字节对像素进行紧缩、位运算和拆分。 1、2、4、8 和 16 位位图需要按字节拆分的像素值最少，因而效率最高。 对于可能已定义的大小，趋向于不规则映射到字节边界的（如 3 或 12）将导致效率低下。


像素值

类型 NativeColor 用于表示像素数组中的像素所存储的值。 调色板信息（cntRGB 和 pRGB，或 nColorScheme）说明如何将像素值映射为红色、绿色和蓝色强度值。

如果 cntRGB 非零，则像素值将作为调色板（32 位 R-G-B 颜色值数组）索引。 （请参阅 pRGB。） 如果 nColorScheme 非零，则它标识从像素值到 R-G-B 值的映射。 可以将其当作硬编码调色板。 （请参阅 nColorScheme。）

如果 cntRGB 和 nColorScheme 均为零，则未定义位图颜色值。

请注意，像素值和颜色之间的这种映射与像素大小没有直接关系。 4096 色位图需要 12 位表示所有颜色值，但是这些位可能会存储在 12 位（紧缩表示）或 16 位像素（非紧缩）中。

透明色是像素值解释中的特例。 对于支持透明色的操作，例如使用 AEE_RO_TRANSPARENT 光栅操作调用 IBITMAP_BltIn() 时，值与透明色 (ncTransparent) 相匹配的像素将作透明处理，即目标中的对应像素保留不修改。ncTransparent 是一个 NativeColor 值，匹配将在像素值而非对应的 R-G-B 强度值上执行。


调色板映射

pPaletteMap 成员为驱动程序软件提供了一种方法来缓存从位图调色板计算所得的信息。
它不单由调色板决定还取决于图形算法，以及可能与该 DIB 相互作用的其它所有位图。 如果没有与该 IDIB 关联的调色板映射对象，此成员将设置为 NULL。

每个 IDIB 实现必须确保在删除 IDIB 自身后，释放 pPaletteMap 对象（如果已设置）。 IDIB_FlushPalette() 宏将执行此任务。

只要 IDIB 的修改影响了像素值的解释（例如 cntRGB、pRGB[]、nColorScheme 或 ncTransparent 被修改），就必须释放其 pPaletteMap。 否则，图形算法可能会在后续调用中继续使用陈旧的数据，甚至是错误的内存。

通常，用户可以忽略此值，除非是在使用 DIB 调色板数据之后（例如，IBitmap 成员函数等图形操作已使用这些数据）对其进行了修改。 在这种情况下，必须调用 IDIB_FlushPalette()。


软件支持

IDIB 提供了广泛的位图配置可能，但实际约束限制了手持设备中其它软件所支持的格式数量。 不是所支持的配置都经过全面优化。 这些限制也因手持设备而异。 不过，DIB 的用途是与图形驱动程序交换位图数据，因此目标设备对特定格式的支持级别对于应用程序软件非常重要。 以下是一些通用的指导原则：

  • 各种手持设备的主显示（无论是单色、灰度还是彩色）都应支持基于调色板的
    1 位、2 位、4 位和 8 位 DIB 位块传输。
  • 颜色映射通常以适宜的方式而不是最精确的方式进行。 1 位和 8 位操作应特别优化。 此外，16 位手持设备支持使用 IDIB_COLORSCHEME_555 或 IDIB_COLORSCHEME_565 配色的 16 位 DIB 格式，但是将 5-5-5 DIB 位块传输到 5-6-5 设备将导致性能降低（反之亦然）。

基于调色板的 8 位 DIB 应可用于所有彩色显示，并且远小于 16 位图像，因此建议彩色图像采用。 由于每个 8 位图像均可选择 256 种颜色，因此颜色精度不成问题。

要包含的头文件列表

需要以下头文件：

AEEBitmap.h

函数列表

此接口的函数包括：

IDIB_AddRef()

IDIB_FlushPalette()

IDIB_QueryInterface()

IDIB_Release()

IDIB_TO_IBITMAP()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDIB_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDIB_Release()

返回函数列表

IDIB_FlushPalette()

说明：

此宏用于释放 IDIB 结构的 pPaletteMap 成员。 任何时候修改 DIB 调色板后都需要使用此宏，因为调色板映射中缓存的信息已不再有效。 该宏首先检查 pPaletteMap 是否为 NULL。 如果是，它将不执行任何操作。 否则，它将调用调色板映射的释放函数，并将 pPaletteMap 设置为 NULL。

原型：

IDIB_FlushPalette(pdib) if ((pdib)->pPaletteMap)
{IQI_Release((pdib)->pPaletteMap);
(pdib)->pPaletteMap = 0;}

参数：

pdibki
[in]
指向 IDIB 结构的指针。

返回值：

无返回值

备注：

无

另请参阅：

无

返回函数列表

IDIB_QueryInterface()

说明：

此函数继承于 IBITMAP_QueryInterface()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDIB

返回函数列表

IDIB_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDIB_AddRef()

返回函数列表

IDIB_TO_IBITMAP()

说明：

此函数提供从 IDIB 接口指针到 IBitmap 接口指针的类型安全转换。 在将 IDIB 接口传递给 IBitmap 函数时将用到此函数。 由于编译器将验证指针类型，所以它比简单转换更安全。

原型：

_inline IBitmap *IDIB_TO_IBITMAP(const IDIB *pIDIB);

参数：

pIDIB
指向 IDIB 接口的指针。

返回值：

返回已转换为 IBitmap* 的 pIDIB。

备注：

无

另请参阅：

IDIB

返回函数列表


IDisplay 接口

IDisplay 接口函数用于在设备显示屏上绘制文本、位图和简单的几何图形，如水平线段、垂直线段和矩形等。 IGraphics 接口 可提供绘制更复杂的线条和图形的方法。 由于所有应用程序都使用 IDisplay 接口，因此创建应用程序后将自动创建 IDisplay 实例。

一些 IDisplay 函数可以在屏幕上绘制文本，并获取有关大小的信息，以便确定其最佳位置。

  • IDISPLAY_DrawText() 可以在屏幕上指定的 x 和 y 坐标处绘制文本字符串。
    您还可以指定文本的字体及其垂直和水平对齐方式，以及用来限制绘制文本的屏幕部分的剪切矩形。
  • IDISPLAY_MeasureText() 可以度量以特定字体显示的文本字符串的宽度。 此函数可用于确定给定屏幕区域内是否能够容纳字符串。
  • IDISPLAY_MeasureTextEx() 是此函数的扩展版本，可用于指定显示文本字符串的可用水平空间（此函数将返回此空间可容纳的字符串的字符数）。
  • IDISPLAY_GetFontMetrics() 用于返回给定字体文本的高度（以像素为单位），
    以便计算屏幕垂直区域可容纳的文本行数。
  • IDISPLAY_GetSymbol() 用于返回与给定符号关联的字符值 (AECHAR)
    （许多设备具有特殊的字符，用于表示设备上的按键或 AM/PM 指示器）。

IDisplay 接口中的几何操作在屏幕的矩形区域中进行。IDISPLAY_EraseRect() 函数可以绘制在 AEERect 结构中指定了坐标的矩形，并指定矩形框及其内部的颜色。

以下函数是IDISPLAY_DrawRect() 的特例，包含一些最常见的用途：

  • IDISPLAY_EraseRect() 用于清除指定的矩形（例如，使用默认的屏幕背景颜色填充矩形）。
  • IDISPLAY_EraseRgn() 用于清除屏幕左上角给定高度和宽度及 x、y 坐标的屏幕区域（而不是输入 IDISPLAY_EraseRect() 的 AEERect 结构）。
  • IDISPLAY_FillRect() 可以使用指定的颜色填充给定的矩形。
  • IDISPLAY_FrameRect() 可以使用默认的边框颜色在给定矩形的四周绘制边框，
    但不修改矩形内部。
  • IDISPLAY_FrameSolidRect() 可以使用默认的边框颜色在给定矩形的四周绘制边框，并使用默认的背景颜色填充矩形内部。
  • IDISPLAY_InvertRect() 可以反转矩形的颜色（此函数可以反相显示当前矩形的
    内容）。
  • IDISPLAY_DrawHLine() 和 IDISPLAY_DrawVLine() 用于在屏幕上绘制水平线段和垂直线段。 这两个函数中都要输入线段长度（以像素为单位）以及起点的 x 和 y 坐标，所绘出的线段颜色为黑色，宽度为一个像素。
  • IDISPLAY_SetColor() 可以为屏幕上显示的给定项目指定颜色。 可指定其颜色的项目包括文本、边框和背景。 颜色指定为 RGB 值。
  • IDISPLAY_BitBlt() 用于在屏幕区域绘制位图图像。 在对此函数进行输入时，您可以指定在其中显示位图的矩形的大小和位置，指向源位图的指针，要绘制源位图部分的 x 和 y 坐标，以及用于结合源位图和目标区域像素的光栅操作。
  • IDISPLAY_Backlight() 可以启用和禁用设备的屏幕荧光（如果有）。
  • IDISPLAY_SetAnnunciators() 可以启用和禁用设备的报警器。 报警器是显示在设备屏幕上的小图像，可以对某些情况（如出现语音邮件或新到 SMS 消息）发出信号通知，每台设备支持的报警器设置均不相同。

上述屏幕绘制操作要在屏幕更新后才生效。IDISPLAY_Update() 可用于更新屏幕。 为尽可能减少不必要的屏幕重绘操作，通常可以在执行多次绘制操作后，调用一次 IDISPLAY_Update()。 此函数可以将更新操作放在稍后执行的任务队列中。函数 IDISPLAY_UpdateEx() 可以强制屏幕立即更新。

使用 IDisplay 接口中的函数

  1. 调用 ISHELL_CreateInstance() 以获取 IDisplay 接口实例。 您还可以使用小程序数据结构中 m_pIDisplay 变量指向的实例。
  2. 调用 IDISPLAY_EraseRect()、IDISPLAY_EraseRgn() 或其它矩形填充函数之一（如果必要），清除要执行绘制操作的屏幕区域。
  3. 使用 IDisplay 绘制操作在屏幕上绘制所需的文本、线段、矩形和位图。
  4. 调用 IDISPLAY_Update() 或 IDISPLAY_UpdateEx() 函数使绘制操作生效。
  5. 如果不再需要IDisplay 接口，调用 IDISPLAY_Release() 释放该接口（小程序终止时，将自动释放小程序数据结构中指向的实例）。

要包含的头文件列表

需要以下头文件：

AEEDisp.h

函数列表

此接口的函数包括：

IDISPLAY_AddRef()

IDISPLAY_Backlight()

IDISPLAY_BitBlt()

IDISPLAY_ClearScreen()

IDISPLAY_Clone()

IDISPLAY_CreateDIBitmap()

IDISPLAY_DrawFrame()

IDISPLAY_DrawHLine()

IDISPLAY_DrawRect()

IDISPLAY_DrawText()

IDISPLAY_DrawVLine()

IDISPLAY_EraseRect()

IDISPLAY_EraseRgn()

IDISPLAY_FillRect()

IDISPLAY_FrameButton()

IDISPLAY_FrameRect()

IDISPLAY_FrameSolidRect()

IDISPLAY_GetClipRect()

IDISPLAY_GetDestination()

IDISPLAY_GetDeviceBitmap()

IDISPLAY_GetFontMetrics()

IDISPLAY_GetSymbol()

IDISPLAY_InvertRect()

IDISPLAY_MeasureText()

IDISPLAY_MeasureTextEx()

IDISPLAY_Release()

IDISPLAY_SetAnnunciators()

IDISPLAY_SetClipRect()

IDISPLAY_SetColor()

IDISPLAY_SetDestination()

IDISPLAY_SetFont()

IDISPLAY_Update()

IDISPLAY_UpdateEx()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDISPLAY_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDISPLAY_Release()

返回函数列表

IDISPLAY_Backlight()

说明：

此函数可根据参数 bOn 启用或禁用设备的屏幕荧光。 屏幕荧光的工作状态完全取决于特定的设备。 您可以使用此函数启用屏幕荧光，但启用多长时间后便再次禁用完全由设备制造商决定。 同样，您可以使用此函数禁用屏幕荧光，但禁用多长时间后便再次启用完全由设备制造商决定。

原型：

void IDISPLAY_Backlight(IDisplay * pIDisplay, boolean bOn)

参数：

pIDisplay | 指向用来控制设备屏幕荧光的 IDisplay 接口对象的指针。
bOn | 如果为 TRUE，则屏幕荧光已启用。 如果为 FALSE，则屏幕荧光已禁用。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDISPLAY_BitBlt()

说明：

此函数可以将对应于像素矩形的数据从指定的源位图位块传输到给定的“显示”区域。 调用此函数后，必须调用 IDISPLAY_Update() 更新屏幕。 如果正在执行一系列的绘制操作，则在完成所有绘制操作后调用一次 IDISPLAY_Update() 就足够了。

原型：

void IDISPLAY_BitBlt
(
IDisplay * pIDisplay,
int xDest,
int yDest,
int cxDest,
int cyDest,
const void * pbmSource,
int xSrc, int ySrc,
AEERasterOp dwRopCode
)

参数：

pIDisplay | 指向要进行位块传输的 IDisplay 接口对象的指针。
xDest | 指定目标矩形区域左上角的 x 坐标。
yDest | 指定目标矩形区域左上角的 y 坐标。
cxDest | 指定目标矩形的宽度。 如果该值大于源位图 (pmSource) 的宽度，则将把该参数值设置为源位图的宽度。
cyDest | 指定目标矩形的高度。 如果该值大于源位图 (pmSource) 的高度，则将该参数值设置为源位图的高度。
pbmSource | 指向 IBitmap 接口、IDIB 接口或源位图的结构的指针。 如果是源位图的结构，则指针指向的数据不包括 AEE 头文件。 如果是 BMP 格式，则该数据可以从 BITMAPFILEHEADER 开始。
xSrc | 指定必须从中开始传输位块的源位图左上角的 x 坐标。
ySrc | 指定必须从中开始传输位块的源位图左上角的 y 坐标。
dwRopCode | 指定在进行位块传输的同时必须使用的“光栅”操作。

返回值：

无

备注：

无

另请参阅：

IDISPLAY_Update()

AEERasterOp

返回函数列表

IDISPLAY_ClearScreen()

说明：

此函数用于清除当前剪切矩形，或者如果未设置剪切矩形时清除整个设备屏幕。

原型：

void IDISPLAY_ClearScreen(IDisplay * pIDisplay)

参数：

pIDisplay
指向 IDisplay 接口对象的指针。

返回值：

无

备注：

无

另请参阅

无

返回函数列表

IDISPLAY_Clone()

说明：

此函数用于创建新的 IDisplay 实例，并将 IDisplay 基本（源）实例的当前设置复制到新实例中。

原型：

int IDISPLAY_Clone(IDisplay * pIDisplay, IDisplay ** ppIDisplayNew);

参数：

pIDisplay | [in] | 指向 IDisplay 基本（源）接口对象的指针
ppIDisplayNew | [out] | 指向已填入新实例地址的接口指针的指针

返回值：

如果成功复制 IDisplay 实例，将返回 SUCCESS。

如果由于内存不足操作失败，将返回 ENOMEMORY。

备注：

此函数对基本 IDisplay 对象无效。

另请参阅：

无

返回函数列表

IDISPLAY_CreateDIBitmap()

说明：

此函数用于创建新的设备无关位图 (DIB)。 IDIB 接口是具有公有数据成员的 IBitmap 接口。 IDIB 指针可转换为 IBitmap 指针，并且适用于任何使用 IBitmap 指针的情形。 对于类型安全转换，请使用 IDIB_TO_IBITMAP() 内联函数。

使用指定宽度、高度和位深度分配内存,以保存行 32 位对齐的像素数组。 假定自顶而下（正宽距）分布,IDIB 成员 cx、cy、nPitch 和 pBmp 将相应进行初始化。 位图的调色板大小、颜色方案和透明色均初始化为零。

调用程序可以直接操作 IDIB 数据成员，以执行进一步的初始化工作。 IDIB 的成员 pRGB 和 pBmp 可以指向未分配给新位图的内存；在这种情况下，只要引用内存的位图存在，调用程序就必须确保位图指针所引用的内存保持有效。 创建引用外部位图数据的 DIB 时，可以将 DIB 的宽度和高度设为零，从而避免将内部内存分配给该位图。

此函数创建的 DIB 对象主要用于向（从）设备相关位图进行位块传输数据。 多数绘制操作或颜色转换函数均未在这些对象中实现，因此通常用于绘制文本或图形的 IDisplay 或 IGraphics 函数无法绘制这些位图。 具体说来，以下 IBitmap 成员函数始终返回 EUNSUPPORTED：

IBITMAP_DrawPixel(),

IBITMAP_GetPixel(),

IBITMAP_SetPixels(),

IBITMAP_DrawHScanline(),

IBITMAP_FillRect(),

IBITMAP_BltOut().

此外，IBITMAP_BltIn() 可通过目标位图的 IBITMAP_BltOut() 实现。

IBITMAP_RGBToNative() 和 IBITMAP_NativeToRGB() 将产生未定义结果。

原型：

int IDISPLAY_CreateDIBitmap
(
IDisplay *pIDisplay,
IDIB **ppIDIB,
uint8 colorDepth,
int16 w,
int16 h
)

参数：

pIDisplay | [in] | 指向 IDISPLAY 接口对象的指针。
ppIDIB | [out] | 指向新 DIB 接口的指针。
colorDepth | [in] | 每个像素所用的位数。
w | [in] | 新位图的宽度（以像素为单位）。
h | [in] | 新位图的高度（以像素为单位）。

返回值：

如果成功，将返回 SUCCESS。

如果没有足够的内存来分配位图缓冲区，将返回 ENOMEMORY。

如果不支持该位图类型，将返回 EUNSUPPORTED。

备注：

无

另请参阅：

IDIB

IDIB_TO_IBITMAP()

返回函数列表

IDISPLAY_DrawFrame()

说明：

此函数可根据系统的色彩分辨率绘制复杂的边框。 它可以绘制单边框和 3D 边框。 向例程传递有效的 clrFill 可以在指定矩形的内部填满指定的颜色。 该指定矩形可根据操作结果的大小进行调整。 这样便允许调用例程并使其自动调整矩形，以便适量偏移后续操作（如文本绘制）。

原型：

int IDISPLAY_DrawFrame
(
IDisplay * pIDisplay,
AEERect * prc,
AEEFrameType ft,
RGBVAL clrFill
)

参数：

pIDisplay | [in] | 指向 IDisplay 接口对象的指针。
prc | [in/out] | 指向源矩形的指针。 如果为 NULL，则未绘制边框。
ft | [in] | 边框类型。
clrFill | [in] | 边框内部的填充类型。

返回值：

此调用可调整输入的矩形。 返回值是每侧边框的像素数目。

备注：

无

另请参阅：

RGBVAL

AEEFrameType

AEERect

返回函数列表

IDISPLAY_DrawHLine()

说明：

此函数用于从给定点绘制一定长度的水平线段。

原型：

void IDISPLAY_DrawHLine
(
IDisplay * pIDisplay,
int16 x,
int16 y,
int16 len
)

参数：

pIDisplay | 指向用于绘制水平线段的 IDisplay 接口对象的指针。
x | 线段起点的 X 坐标。
y | 线段起点的 Y 坐标。
len | 线段的长度。

返回值：

无

备注：

IDISPLAY_DrawHLine 始终以 RGB_BLACK 绘制这些水平线段和垂直线段。

另请参阅：

IDISPLAY_DrawVLine()

返回函数列表

IDISPLAY_DrawRect()

说明：

此函数可以使用指定的颜色和标记绘制给定的矩形。 调用此函数后，必须调用 IDISPLAY_Update() 更新屏幕。 如果正在执行一系列的绘制操作，则在完成所有绘制操作后调用一次 IDISPLAY_Update() 就足够了。

原型：

void IDISPLAY_DrawRect
(
IDisplay * pIDisplay,
const AEERect * pRect,
RGBVAL clrFrame,
RGBVAL clrFill,
uint32 dwFlags
)

参数：

pIDisplay
指向用于绘制矩形的 IDisplay 接口对象的指针。
pRect
指向用于定义要绘制矩形坐标的 AEERect 结构的指针。 这些坐标参照屏幕坐标，屏幕左上角的坐标为 0,0。
clrFrame
指定用于绘制矩形边框（外框）的颜色。 此参数仅在 dwFlags 包含标记 IDF_RECT_FRAME 时使用。
clrFill
指定矩形的填充颜色。 此参数仅在 dwFlags 包含标记 IDF_RECT_FILL 时使用。
dwFlags
指定用于绘制矩形的标记， 可以是以下一个或多个标记的逻辑“或”：
  • IDF_RECT_FRAME: 仅绘制矩形的外框。
  • IDF_RECT_FILL: 使用 clrFill 颜色填充矩形。
  • IDF_RECT_INVERT: 反转指定矩形的内容。 设置此标记后，clrFrame 和 clrFill 参数将不起作用。

返回值：

无

备注：

如果 pRect 为 NULL，且 dwFlags 包含 IDF_RECT_FILL，则此函数将使用 clrFill 清除整个屏幕。 如果 pRect 为 NULL，且无 IDF_RECT_FILL 标记，则此函数会将 pRect 作为空矩形处理。

另请参阅：

AEERect

RGBVAL

IDISPLAY_Update()

返回函数列表

IDISPLAY_DrawText()

说明：

此函数可以使用给定的字体在给定位置绘制给定的文本，并将该文本限定在剪切矩形中。 调用此函数后，必须调用 IDISPLAY_Update() 更新屏幕。 如果正在执行一系列的绘制操作，则在完成所有绘制操作后调用一次 IDISPLAY_Update() 就足够了。

原型：

int IDISPLAY_DrawText
(
IDisplay * pIDisplay,
AEEFont Font,
const AECHAR * pcText,
int nChars,
int x,
int y,
const AEERect * prcBackground,
uint32 dwFlags
)

参数：

pIDisplay
指向用于绘制文本的 IDisplay 接口对象的指针。
Font
指定用于绘制文本的字体。
pcText
包含要绘制的字符串。
nChars
指定 pcText 中的字符数。 如果字符数为 -1，此函数将自动计算字符串长度。
x
指定屏幕上要绘制的文本位置的 y 坐标。 屏幕左上角的坐标为 [0,0]。 如果设置了水平对齐标记，此参数将不起作用。
y
指定屏幕上要绘制的文本位置的 y 坐标。 屏幕左上角的坐标为 [0,0]。 如果设置了垂直对齐标记，此参数将不起作用。
prcBackground
指定剪切矩形的坐标。 如果为 NULL，则将整个屏幕作为剪切矩形。 不得在此剪切矩形外绘制文本。 如果必要，可以从字符串的右边开始剪切字符。 如果指定了任何一个矩形标记。，
则该矩形也用作填充。
dwFlags
指定用于绘制屏幕的标记， 可以是以下每个条目中选项之一的逻辑“或”：
  • 水平对齐标记之一（IDF_ALIGN_LEFT、IDF_ALIGN_CENTER、
    IDF_ALIGN_RIGHT）
  • 垂直对齐标记之一（IDF_ALIGN_TOP、IDF_ALIGN_MIDDLE、
    IDF_ALIGN_BOTTOM）
  • 文本格式标记之一（IDF_TEXT_UNDERLINE、IDF_TEXT_INVERTED）
  • 矩形格式标记之一（IDF_RECT_FRAME、IDF_RECT_FILL、IDF_RECT_INVERT）--- 这些标记作用于 prcBackground 矩形，将 CLR_USER_BACKGROUND 作为填充颜色，CLR_USER_FRAME 作为边框颜色。 如果指定了任何一个矩形标记。，则该矩形也用作填充。

如果没有指定对齐标记，则文本的位置将由参数 x 和 y 决定。默认情况下，该文本将挡住其后的所有内容。 为避免出现这种情况，请使用 IDF_TEXT_TRANSPARENT
标记。 BREW Emulator 当前不支持 IDF_ALIGN_SPREAD 和 IDF_ALIGN_FILL。

示例：

IDF_ALIGN_CENTER | IDF_ALIGN_TOP | IDF_TEXT_UNDERLINE 组合可以在剪切矩形上部（垂直方向）的中心（水平方向）位置绘制带下划线的文本。

返回值：

如果成功，将返回 SUCCESS。

如果失败，将返回 EFAILED。

如果不支持输入类型，将返回 EUNSUPPORTED。

备注：

无

另请参阅：

IDISPLAY_Update()
AEEFont
AEERect

返回函数列表

IDISPLAY_DrawVLine()

说明：

此函数用于从给定点绘制一定长度的垂直线段。

原型：

void IDISPLAY_DrawVLine
(
IDisplay * pIDisplay,
int16 x,
int16 y,
int16 len
)

参数：

pIDisplay | 指向用于绘制垂直线段的 IDisplay 接口对象的指针。
x | 线段起点的 X 坐标。
y | 线段起点的 Y 坐标。
len | 线段的长度。

返回值：

无

备注：

IDISPLAY_DrawVLine 始终以 RGB_BLACK 绘制这些水平线段和垂直线段。

另请参阅：

IDISPLAY_DrawHLine()

返回函数列表

IDISPLAY_EraseRect()

说明：

此函数可以使用默认的背景颜色（例如，与项目 CLR_USER_BACKGROUND 关联的颜色）填充给定的矩形。

原型：

void IDISPLAY_EraseRect(IDisplay * pIDisplay, AEERect * pRect)

参数：

pIDisplay | 指向用于清除矩形的 IDisplay 接口对象的指针。
pRect | 指向要反转其颜色的矩形的有效指针。

返回值：

无

备注：

无

另请参阅：

AEERect

返回函数列表

IDISPLAY_EraseRgn()

说明：

此函数可以使用默认的背景颜色（如，与 CLR_USER_BACKGROUND 关联的颜色）填充给定坐标封闭的区域。

原型：

void IDISPLAY_EraseRgn
(
IDisplay * pIDisplay,
int16 x,
int16 y,
uint16 cx,
uint16 cy
)

参数：

pIDisplay | 指向用于填充区域的 IDisplay 接口对象的指针。
x | 区域左上角的 X 坐标。
y | 区域左上角的 Y 坐标。
cx | 区域的宽度。
cy | 区域的高度。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDISPLAY_FillRect()

说明：

此函数用于绘制矩形，并使用指定颜色填充矩形。

原型：

void IDISPLAY_FillRect
(
IDisplay * pIDisplay,
AEERect * pRect,
RGBVAL clrFill
)

参数：

pIDisplay | 指向用于填充矩形的 IDisplay 接口对象的指针。
pRect | 指向要使用指定颜色填充的矩形的有效指针。
clrFill | 指定用于填充矩形的颜色。

返回值：

无

备注：

无

另请参阅：

AEERect

RGBVAL

返回函数列表

IDISPLAY_FrameButton()

说明：

此函数可根据系统的色彩分辨率绘制 3D 边框按钮。 如果 bPressed 为 TRUE，此函数将绘制凹下的按钮，如果 bPressed 为 FALSE，则绘制凸起的按钮。 此函数可根据系统的色彩分辨率绘制复杂的边框。 它可以绘制单边框和 3D 边框。 向例程传递有效的 clrFill 可以在指定矩形的内部填满指定的颜色。 该指定矩形可根据操作结果的大小进行调整。 这样便允许调用例程并使其自动调整矩形，以便适量偏移后续操作
（如文本绘制）。

原型：

void IDISPLAY_FrameButton
(
IDisplay * pIDisplay,
AEERect * prc,
boolean bPressed,
RGBVAL clrFill
)

参数：

pIDisplay | [in] | 指向 IDisplay 接口对象的指针。
prc | [in/out] | 指向源矩形的指针。
bPressed | [in] | 按钮凹下/凸起指示器。
clrFill | [in] | 边框内部的填充类型。

返回值：

此调用调整输入的矩形 (prc)。

备注：

无

另请参阅：

AEERect

RGBVAL

返回函数列表

IDISPLAY_FrameRect()

说明：

此函数用于绘制矩形的边框。 绘制边框的颜色是当前分配给 CLR_USER_FRAME 的颜色。

原型：

void IDISPLAY_FrameRect(IDisplay * pIDisplay, AEERect * pRect)

参数：

pIDisplay | 指向用于绘制矩形的 IDisplay 接口对象的指针。
pRect | 指向需绘制其边框的矩形的有效指针。

返回值：

无

备注：

无

另请参阅：

AEERect

返回函数列表

IDISPLAY_FrameSolidRect()

说明：

此函数用于绘制矩形的边框，并使用某种颜色填充矩形。 绘制边框的颜色是当前分配给 CLR_USER_FRAME 的颜色。 填充矩形的颜色是当前分配给CLR_USER_BACKGROUND 的颜色。

原型：

void IDISPLAY_FrameSolidRect(IDisplay * pIDisplay, AEERect * pRect)

参数：

pIDisplay | 指向用于绘制矩形的 IDisplay 接口对象的指针。
pRect | 指向要绘制和填充的矩形的有效指针。

返回值：

无

备注：

无

另请参阅：

AEERect

返回函数列表

IDISPLAY_GetClipRect()

说明：

此函数用于返回 IDISPLAY_SetClipRect() 设置的当前剪切矩形，或者默认的剪切矩形（全屏尺寸）。 剪切矩形是当前所选显示位图的有效绘制区域。 在剪切矩形之外执行的任何绘制均不予显示。

原型：

void IDISPLAY_GetClipRect(IDisplay * pIDisplay, AEERect *prc)

参数：

pIDisplay | [in] | 指向 IDisplay 接口对象的指针
prc | [out] | 指向接收当前剪切矩形的 AEERect 的指针。

返回值：

无

备注：

此函数只返回指定 IDisplay 实例的剪切矩形。

另请参阅：

AEERect

IDISPLAY_SetClipRect()

返回函数列表

IDISPLAY_GetDestination()

说明：

此函数用于获取 IDISPLAY 函数将要渲染的目标位图。

原型：

IBitmap* IDISPLAY_GetDestination(IDisplay *pIDisplay)

参数：

pIDisplay
[in]
指向 IDISPLAY 接口对象的指针。

返回值：

指向当前目标位图的指针。 IDISPLAY_GetDestination() 在返回时增加位图的引用
计数。

备注：

如果此函数返回 NULL，则表明出现错误。

另请参阅：

IBitmap 接口

IDISPLAY_SetDestination()

返回函数列表

IDISPLAY_GetDeviceBitmap()

说明：

此函数用于获取设备（屏幕）位图。 设备位图是指调用 IDISPLAY_Update() 时将其内容复制到屏幕的位图。

原型：

int IDISPLAY_GetDeviceBitmap(IDisplay *pIDisplay, IBitmap **ppIBitmap)

参数：

pIDisplay | [in] | 指向 IDISPLAY 接口对象的指针。
ppIBitmap | [out] | 指向设备位图接口的指针。

返回值：

如果成功，将返回 SUCCESS。

否则，返回错误代码。

备注：

此函数将在内部增加作为第二参数返回的 IBitmap 指针引用（如果返回了 IBitmap 指针）。 此指针必须由应用程序开发者通过 IBITMAP_Release() 释放。

设备位图可由所有 BREW 应用程序共享。 除了像素数据外，还应注意不要修改任何数据成员（使用 IDIB 时可能会修改数据成员）。

设备位图的透明色例外。 要从设备位图执行透明位块传输，则应用程序应在执行该操作前设置透明色。 设置透明色之前，或调用应用程序的外部函数之后（而不是位块传输函数），不要假定透明色。

请注意，兼容位图将继承创建它们的位图的透明色。 如果设备位图的透明色未知，
则由它创建的任何后台屏幕的初始透明色也未知。

另请参阅：

无

返回函数列表

IDISPLAY_GetFontMetrics()

说明：

此函数用于获取指定字体的信息， 如指定字体的升距和降距值的信息。

注意： 升距 + 降距 = 字符总高度，但不包括任何前导空格。

原型：

int IDISPLAY_GetFontMetrics
(
IDisplay * pIDisplay,
AEEFont Font,
int * pnAscent,
int * pnDescent
)

参数：

pIDisplay | [in] | 指向要获取其字体量度的 IDisplay 接口对象的指针。
Font | [in] | 指定要获取其升距和降距信息的字体类型。
pnAscent | [in/out] | 输入时，必须为指向 int 的有效指针。 返回时，指针将指向表示指定字体升距值的整数。可以输入 NULL 指针，在该情况下，返回时仍为 NULL。
pnDescent | [in/out] | 输入时，必须为指向 int 的有效指针。 返回时，指针将指向表示指定字体降距值的整数。 可以输入 NULL 指针，在该情况下，返回时仍为 NULL。

返回值：

如果成功，将返回指定字体的字符高度。 返回值为指定字体升距和降距值的总和。

如果失败，将返回 EFAILED。

备注：

无

另请参阅：

AEEFont

返回函数列表

IDISPLAY_GetSymbol()

说明：

此函数用于返回与指定符号值相对应的 AECHAR 值。

原型：

AECHAR IDISPLAY_GetSymbol
(
IDisplay * pIDisplay,
AEESymbol sym,
AEEFont fnt
)

参数：

pIDisplay | 指向用于更改用户项目颜色的 IDisplay 接口对象的指针。
sym | 请求的符号。
fnt | 请求的字体。

返回值：

与指定符号相关联的 AECHAR。

备注：

如果设备上不存在该符号，将返回空字符 (AECHAR) ' '。

另请参阅：

AEEFont
AEESymbol

返回函数列表

IDISPLAY_InvertRect()

说明：

此函数用于反转给定矩形中的颜色。 它将颜色反转并使用已反转的颜色图案重新填充矩形。

原型：

void IDISPLAY_InvertRect(IDisplay * pIDisplay, AEERect * pRect)

参数：

pIDisplay | 指向用于反转矩形的 IDisplay 接口对象的指针。
pRect | 指向要反转其颜色的矩形的有效指针。

返回值：

无

备注：

无

另请参阅：

AEERect

返回函数列表

IDISPLAY_MeasureText()

说明：

此函数用于度量使用指定字体绘制的给定文本字符串的宽度。

原型：

int IDISPLAY_MeasureText
(
IDisplay * pIDisplay,
AEEFont Font,
const AECHAR * pcText
)

参数：

pIDisplay | 指向用于度量给定文本宽度的 IDisplay 接口对象的指针。
Font | 指定用于度量给定文本宽度的字体。 此函数用于度量使用此字体绘制的给定文本字符串的宽度。
pcText | 指向要度量字符串的指针。

返回值：

如果成功，将返回在字符串 pcText 中绘制字符所需的像素数目。

否则，返回 0（零）。

备注：

无

另请参阅：

AEEFont

返回函数列表

IDISPLAY_MeasureTextEx()

说明：

此函数用于度量使用指定字体绘制的给定文本字符串的宽度。 返回值是字符串的实际像素宽度。

原型：

int IDISPLAY_MeasureText
(
IDisplay * pIDisplay,
AEEFont Font,
const AECHAR * pcText,
int nChars,
int nMaxWidth,
int * pnFits
)

参数：

pIDisplay | [in] | 指向用于度量给定文本宽度的 IDisplay 接口对象的指针。
Font | [in] | 指定用于度量给定文本宽度的字体。 此函数用于度量使用此字体绘制的给定文本字符串的宽度。
pcText | [in] | 指向要度量字符串的指针。
nChars | [in] | 指定 pcText 中的字符数。 如果字符数为1，此函数将自动计算字符长度。
nMaxWidth | [in] | 指定可用于绘制文本的最大可用像素宽度。 如果将 nMaxWidth 设置为 1，则将度量文本字符串的 nChars 部分，并且返回的 * pnFits 始终是整个文本的长度。 如果将 nMaxWidth > 0，则它表示可在其中纳入文本的最大可用像素宽度。此函数计算实际此范围内可容纳的最大字符数，并在 * pnFits 中返回字符数目，返回值为这些字符的实际像素宽度。
pnFits | [in/out] | 输入时，必须为指向整数的有效指针。 返回时，该指针指向一个整数，该整数表示符合通过 nMaxWidth 指定的指定像素宽度的字符数。 如果 nMaxWidth 为 -1，则该参数将指向表示给定字符串 pcText 总长度的整数。

返回值：

如果成功，则返回要绘制字符的实际像素宽度。 可在此宽度内绘制的字符数包含在
* pnFits 中。

如果失败，将返回 0（零）。

备注：

无

另请参阅：

AEEFont

返回函数列表

IDISPLAY_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDISPLAY_AddRef()

返回函数列表

IDISPLAY_SetAnnunciators()

说明：

此函数用于启用或禁用指定的报警器。 是否支持此函数以及函数的行为完全取决于特定的设备。

以下为报警器的完整列表：

ANNUN_MSG | 语音邮件
ANNUN_NET_MSG | 网络消息
ANNUN_ALARMCLOCK | 闹钟
ANNUN_NET_LOCK | 设备锁定
ANNUN_STOPWATCH | 秒表
ANNUN_COUNTDOWN | 倒数计时时钟
ANNUN_SILENCEALL | 振铃关闭

设备可以支持上列部分或全部报警器。

注意：在 BREW 当前版本中，BREW Emulator 不支持此函数。
Emulator不显示报警器。

原型：

void IDISPLAY_SetAnnunciators
(
IDisplay * pIDisplay,
uint16 wVal,
uint16 wMask
)

参数：

pIDisplay | 指向用于启用/禁用报警器的 IDisplay 接口对象的指针。
wVal | 指定该函数要启用或禁用的报警器组， 可以是上面定义的一个或多个报警器标记的逻辑“或”。
wMask | 对于 wVal 中包含的每个报警器标记，此处相应的位指明是启用还是禁用报警器。

返回值：

无

备注：

要启用 ANNUN_MSG 和 ANUN_NET_MSG 报警器，并禁用 ANNUN_COUNTDOWN 报警器，请使用以下代码：

uint16 wVal = 0;
uint16 wMask = 0;
wVal |= ANNUN_MSG | ANNUN_NET_MSG | ANNUN_COUNTDOWN;
wMask |= ANNUN_MSG | ANNUN_NET_MSG;
IDISPLAY_SetAnnunciators(pIDisplay,wVal,wMask);

另请参阅：

无

返回函数列表

IDISPLAY_SetClipRect()

说明：

此函数用于设置 IDisplay 实例的剪切矩形。 剪切矩形是当前所选显示位图的有效绘制区域。 在剪切矩形之外执行的任何绘制均不予显示。

原型：

void IDISPLAY_SetClipRect(IDisplay * pIDisplay, const AEERect *prc)

参数：

pIDisplay | [in] | 指向 IDisplay 接口对象的指针
prc | [in] | 要设置的剪切矩形

返回值：

无

备注：

将 IDisplay 剪切矩形设置为 prc 和目标位图指向的矩形的交集。 如果 prc 与目标位图不相交，则结果剪切矩形为空矩形 (0,0,0,0)，后续的 IDisplay 操作将无法写入目标位图。 如果 prc->dx 或 prc->dy 为零或负，结果也是空矩形。

此函数仅设置指定 IDisplay 实例的剪切矩形。 要将剪切矩形重置为（默认）整个屏幕的尺寸，请在 prc 参数中传递值 NULL (0)。

副作用：

将输出剪切到所传递矩形内，从而影响 IDisplay 实例的其它所有绘制函数。

另请参阅：

AEERect

IDISPLAY_GetClipRect()

返回函数列表

IDISPLAY_SetColor()

说明：

此函数用于设置指定用户项目的颜色。 用户项目列在 AEEClrItem 枚举的开始部分。
这些项目具有 CLR_USER 前缀。 系统项目（例如，位于 AEEClrItem 枚举结尾具有 CLR_SYS 前缀的项目）的颜色无法更改。 项目的颜色可以设置为特定的 RGB 值，
也可以设置为 AEEClrItem 枚举中其它项目的颜色。 例如：

要将项目 CLR_USER_TEXT 的颜色设置为与项目 CLR_SYS_TITLE_TEXT 相同的颜色，请使用以下代码：

IDISPLAY_SetColor(pIDisplay, CLR_USER_TEXT, CLR_SYS_TITLE_TEXT)

要设置为白色，请使用以下代码：

IDISPLAY_SetColor(pIDisplay ,CLR_USER_TEXT, RGB_WHITE)

要设置为任何特定的 RGB 值，请使用以下代码：

IDISPLAY_SetColor(pIDisplay, CLR_USER_TEXT, MAKE_RGB(0x40,0x30,0x50))

原型：

RGBVAL IDISPLAY_SetColor
(
IDisplay * pIDisplay,
AEEClrItem item,
RGBVAL rgb
)

参数：

pIDisplay | 指向用于更改用户项目颜色的 IDisplay 接口对象的指针。
item | 如果成功，将指定需要更改颜色的用户项目。 此项目必须是 AEEClrItem 枚举中具有 CLR_USER 前缀的项目之一。
rgb | 指定与 item 参数中提及的项目关联的新颜色， 它可以是 AEEClrItem 枚举中项目的索引，也可以是 RGB 值。

返回值：

如果成功，将返回原来与 item 关联的颜色。

如果失败，将返回 RGB_NONE。

备注：

无

另请参阅：

AEEClrItem
RGBVAL

返回函数列表

IDISPLAY_SetDestination()

说明：

此函数用于设置 IDISPLAY 函数将要渲染的目标位图。

原型：

int IDISPLAY_SetDestination(IDisplay *pIDisplay, IBitmap *pDst)

参数：

pIDisplay | 指向 IDISPLAY 接口对象的指针。
pDst | 用于渲染的 IBitmap 接口指针，如果为 NULL 则设为屏幕位图。

返回值：

如果成功，将返回 SUCCESS。

否则，将返回 EFAILED。

备注：

实例化 IDisplay 后，默认位图为屏幕位图。 使用该函数时将 pDst 设为 NULL 可恢复至默认位图。

另请参阅：

IBitmap 接口

IDISPLAY_GetDestination()

返回函数列表

IDISPLAY_SetFont()

说明：

此函数可以设置用于绘制指定 AEEFont 的 IFont。 返回值为当前正在使用的 IFont。

原型：

IFont *IDISPLAY_SetFont(IDisplay * pIDisplay, AEEFont nFont, IFont *piNewFont)

参数：

pIDisplay | 指向 IDisplay 接口对象的指针
nFont | 字体指示符
piNewFont | IFont 指针

返回值：

如果成功，将返回原来与 nFont 相关联的 IFont 。

如果设置失败，将返回 NULL。

备注：

应用程序应注意释放返回的 IFont，或者为准确起见，保存原来的 IFont，以便在退出应用程序时进行恢复。 当前，仅支持系统范围的单个 IDisplay，因此调用 IDisplay_SetFont() 将影响所有 BREW 应用程序。 由于应用程序和 IDisplay 仅仅在交换引用计数已经为正的指针，因而传递输入的 IFont piNewFont 以及返回的 IFont 都不增加其引用计数。 所以，应用程序在将 piNewFont 传递至 IDisplay_SetFont() 后，
不允许对其调用 Release()。

另请参阅：

无

返回函数列表

IDISPLAY_Update()

说明：

此函数用于指示已在设备位图上执行绘制操作，并且应将这些更改传至显示硬件。 IDisplay、IGraphics 和 IBitmap 方法在设备位图上的绘制并不会直接反映到显示硬件。 只有更新物理显示时，用户才能够看见结果。 此函数可排列实际的更新操作，因此能够重复调用而不会对性能产生不良影响。 实际显示将在应用程序向 BREW 发出程序控制后进行异步更新。

原型：

void IDISPLAY_Update(IDisplay * pIDisplay)

参数：

pIDisplay
指向要更新的 IDisplay 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IDISPLAY_UpdateEx()

说明：

此函数用于指示已在设备位图上执行绘制操作，并且应将这些更改传至显示硬件。 IDisplay、IGraphics 和 IBitmap 方法在设备位图上的绘制并不会直接反映到显示硬件。 只有更新物理显示时，用户才能够看见结果。 此函数可排列实际的更新操作，因此能够重复调用而不会对性能产生不良影响。 实际显示将在应用程序向 BREW 发出程序控制后进行异步更新。

原型：

void IDISPLAY_UpdateEx(IDisplay * pIDisplay, boolean bDefer)

参数：

pIDisplay | 指向要更新的 IDisplay 接口对象的指针。
bDefer | 指明是要立即更新还是延迟更新屏幕的布尔标记。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表


IDNS 接口

IDNS 提供了一种执行 DNS（域名系统）查询的方式。IDNS 提供了一种比 INETMGR_GetHostByName() 更通用的 DNS 客户机接口。它支持交替请求类型和复合查询。DNS 客户机将保持对 DNS 服务器的跟踪，并处理重发和超时。IDNS 将域名转换为 DNS 协议表示，并提供方法对响应中的压缩域名进行解码。用户负责指定 DNS“问题”记录的内容、定位响应中的重要数据并解释这些值。UDP 是唯一支持的传输方式。请求和响应均限定为 512 字节。

要包含的头文件列表

需要以下头文件：

aeedns.h

函数列表

此接口的函数包括：

IDNS_AddQuestion()

IDNS_AddRef()

IDNS_GetResponse()

IDNS_ParseDomain()

IDNS_Release()

IDNS_Start()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IDNS_AddQuestion()

说明：

此函数用于将一个问题添加至请求中的问题记录集。此函数必须在 Start() 之前调用。可能需要调用多次，以构造由多个问题记录组成的请求消息。

原型：

int IDNS_AddQuestion (
IDNS *pIDNS,
AEEDNSType nType,
AEEDNSClass nClass,
const char *pszDomain
)

参数：

nType | DNS 问题类型
nClass | DNS 类
pszDomain | 以零结尾的字符串表示点分格式的域名。类似"example.com." 中的单点终止符是可以接受的，并与无终止点域名的处理方式相同。注意：不支持域名搜索路径和相对域名。

返回值：

如果返回 SUCCESS，则表示已将问题添加至请求消息中。

如果新问题将使 DNS 消息超出最大大小（UDP 上的 DNS 最大为 512 字节），则返回 EFAILED。

如果域名残缺，则返回 EBADPARM。

如果 IDNS 的状态不适于添加问题，则返回 AEE_NET_EINVAL。在调用 Start() 之后，不能添加问题。

返回值可能包括其它错误，调用者应验证 IDNS_AddQuestion() 是否已成功。

备注：

IDNS 将所有的域都当作完全限定域来处理。不存在域后缀搜索列表；所提供的域字符串也不附加任何后缀。同 INETMGR_GetHostByName() 一样，冒号 (:)、斜杠 (/) 和逗号 (,) 字符不分隔域名。构造问题记录时，IDNS 不使用域名的压缩格式。

另请参阅：

AEEDNSType

AEEDNSClass

返回函数列表

IDNS_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDNS_Release()

返回函数列表

IDNS_GetResponse()

说明：

查询完成后，将调用此函数以获取 DNS 响应。如果成功，它将返回指向包含 DNS 响应说明的结构的指针。响应数据包含指向结构的指针；所引用的内存仅在 IDNS 对象的使用期内有效。释放 IDNS 接口后，不应保留或使用这些指针。

原型：

int IDNS_GetResponse(IDNS *pIDNS, const AEEDNSResponse **pResp);

参数：

pIDNS | [in] | 指向 IDNS 接口对象的指针。
pResp | [out] | 指向说明响应的结构的指针。

返回值：

SUCCESS：接收到 DNS 服务器的响应消息；*pResp 将说明结果。此处的“成功”并不意味着查询成功，而只表示收到响应。应用程序必须检查 AEEDNSResponse 结构，以确定响应中是否存在所请求的数据。

在所有出错的情况下，*pResp 将指向一个空的 AEEDNSResponse 结构。关于其中的内容不应作任何假设。

错误代码包括：

如果因内存分配故障阻碍了请求或响应，则为 ENOMEMORY。

如果转发超时（无服务器响应），则为 AEE_NET_ETIMEDOUT。

如果发生套接字级错误，则为 AEE_NET_ENETNONET。

备注：

无

另请参阅：

AEEDNSResponse

返回函数列表

IDNS_ParseDomain()

说明：

此函数将域名的 DNS 表示转换为以零结尾的使用点 (.) 或破折号 (-) 分隔符的
字符串。

原型：

char *IDNS_*ParseDomain(IDNS *pIDNS, const byte *pbyDomain, int *pcb);

参数：

pIDNS | 指向 IDNS 接口对象的指针。
pbyData | 指向域名开头的指针。此指针必须按照 AEEDNSItem 记录的说明指向 DNS 响应数据。它可用于解码 pbyDomain 值，或解码 pbyData[] 数组内的值。
pcb | 指向保存域名（在源字节数组中，而非结果字符串中）占用字节数的值的指针。在域名残缺的情况下，*pcb 将设置为零。如果 pcb==NULL，则它将被 忽略。

返回值：

如果成功，则返回以零结尾的表示主机名的字符串；如果失败，返回 NULL。域名将以点分格式返回，且末尾处无终止点字符。失败的原因可能是分配失败或域名残缺；*pcb 可用来区分这两个原因。

备注：

无

另请参阅：

无

返回函数列表

IDNS_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IDNS_AddRef()

返回函数列表

IDNS_Start()

说明：

此函数用于启动查询，并调度要调用的回调。为防止启动回调，并取消操作，用户应释放所有对 IDNS 的引用。不能两次调用 Start()。

原型：

IDNS_Start(IDNS *pIDNS, PFNNOTIFY pfn, void *pcxt);

参数：

pIDNS | 指向 IDNS 接口对象的指针。
pfn | 操作完成后要调用的函数。只有在启动操作成功（即 Start() 返回 SUCCESS）时，才会调用此函数。
pv | 调用 pfn() 后传递给它的空指针。

返回值：

错误代码：

如果操作启动，则为 SUCCESS。首次调用时应总是成功。

如果多次调用此函数，则为 AEE_NET_EINVAL。

备注：

释放所有对 IDNS 对象的引用将取消该操作，并阻止调用回调。

另请参阅：

PFNNOTIFY

返回函数列表


IFile 接口

IFile 接口函数使您可以读取和修改使用 IFileMgr 接口创建的文件的内容。 要获取文件的 IFile 接口实例，可以为该文件调用 IFILEMGR_OpenFile()。 然后按照本节后面说明的操作，使用 IFILEMGR_OpenFile() 返回的 IFile 接口指针来访问该文件。 访问结束后，调用 IFILE_Release() 关闭文件。

注意：应用程序必须具有 PL_FILE 或 PL_SYSTEM 优先级，才能使用 IFILE_Write() 或 IFILE_Truncate() 修改文件。 应用程序必须具有 PL_SHARED_WRITE 或 PL_SYSTEM 优先级，才能为共享应用程序目录中的文件调用这些函数。

IFILE_GetInfo() 可以返回有关打开文件的信息，包括名称、大小和创建时间信息（如果文件未打开，通过以文件名作为输入来调用 IFILEMGR_GetInfo()，可以获取相同的信息）。

IFILE_Read() 可以从文件中读取指定数量的字节，并将其复制到应用程序的字符缓冲区。

IFILE_Write() 可以将大量字节从包含要写入数据的字符缓冲区写入文件。 所有读写操作都与当前的文件指针相关，该指针可以确定下一个要读写的文件字节。 最初，指针指向文件的第一个字节，但是，如果以附加方式打开文件，指针会指向文件最后一个字节之后的位置。
每次对文件的读写都会使指针指向读取或写入的最后一个字节之后的位置。 调用 IFILE_Seek() 可以将指针指向文件中的特定位置，并获得指针的当前值，以便在文件的任意位置进行读写。

IFILE_Truncate() 可以减小文件的大小，也就是在文件末尾处删除被截断的内容。

使用 IFile 接口函数

  1. 如有必要，调用 ISHELL_CreateInstance() 以获取 IFile 接口的实例。
  2. 如果要访问的文件尚不存在，
    • 调用 IFILEMGR_OpenFile() 创建文件，并输入文件名。 创建之后，文件便会打开以供读取和写入。
    • 另外，可以调用 IFILEMGR_OpenFile() 打开文件，并根据需要访问的类型执行读取、读写或者附加操作。
  3. 如有必要，请使用步骤 2 中获取的 IFile 指针调用 IFILE_Seek() 来确定文件指针的位置，然后调用 IFILE_Read() 和 IFILE_Write()，根据需要对文件执行读写操作。
  4. 如果需要，您可以调用 IFILE_GetInfo() 获取有关文件的信息，并可以调用 IFILE_Truncate() 截断文件。
  5. 访问结束后，调用 IFILE_Release() 关闭文件。

注意：当前版本的 BREW 不支持 HIDDEN 和 DIR 文件属性。

要包含的头文件列表

需要以下头文件：

AEEFILE.h

函数列表

此接口的函数包括：

IFILE_AddRef()

IFILE_Cancel()

IFILE_GetInfo()

IFILE_GetInfoEx()

IFILE_Read()

IFILE_Readable()

IFILE_Release()

IFILE_Seek()

IFILE_SetCacheSize()

IFILE_Truncate()

IFILE_Write()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IFILE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IFILE_Release()

返回函数列表。

IFILE_Cancel()

说明：

此函数用于取消使用 IFILE_Readable()在此 IFile 接口对象中注册的回调。

原型：

void IFILE_Cancel(IFile * pIFile, PFNNOTIFY pfn, void * pUser)

参数：

pIFile | 指向 IFile 接口对象的指针，该对象的已注册回调函数将被取消。
pfn | 回调函数的地址。
pUser | 调用回调函数时传递给它的用户定义数据。

返回值：

无

备注：

此函数将忽略 pfn 和 pUser 参数的值。

另请参阅：

PFNNOTIFY

IFILE_Readable()

返回函数列表

IFILE_GetInfo()

说明：

此函数用于获取 IFile 接口对象所指文件的创建日期、大小、名称和属性。

原型：

int IFILE_GetInfo(IFile * pIFile, FileInfo * pInfo)

参数：

pIFile | [in] | 指向 IFile 接口对象的指针。
pInfo | [out] | 文件信息占位符。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

文件信息返回到 pInfo 提供的 FileInfo 结构中。

另请参阅：

FileInfo

IFILEMGR_GetInfo()

返回函数列表

IFILE_GetInfoEx()

说明：

此函数用于获取已标识文件的扩展信息。 扩展文件信息包含于 AEEFileInfoEx 结构中。

原型：

int IFILE_GetInfoEx(IFile * pIFile, AEEFileInfoEx * pi);

参数：

pIFile | [in] | 指向 IFile 接口对象的指针
pi | [out] | 扩展文件信息占位符

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

无

另请参阅：

AEEFileInfoEx

IFILEMGR_GetInfoEx()

返回函数列表

IFILE_Read()

说明：

此函数用于从打开的文件中读取指定数量的字节。 读取操作是无阻碍的。

原型：

int32 IFILE_Read(IFile * pIFile, void * pBuffer, uint32 dwCount)

参数：

pIFile | [in] | 指向 IFile 接口对象的指针。
pBuffer | [out] | 从中读取文件数据的缓冲区。
dwCount | [in] | 要读取的字节数。

返回值：

如果成功，则返回读取的字节数。

如果失败，则返回 0（零）。

备注：

要从文件中读取数据，必须先打开文件。 有关打开文件的详细信息，请参阅
IFileMgr 接口的 IFILEMGR_OpenFile() 函数。 从 IFile 接口对象中文件指针所在的位置开始读取字节。 您可以使用 IFILE_Seek() 函数重新确定文件指针在文件中的位置。

副作用：

读取操作结束后，IFile 接口对象的文件指针指向所读字节块的末尾。

另请参阅：

IFILEMGR_OpenFile()

IFILE_Write()

IFILE_Seek()

返回函数列表

IFILE_Readable()

说明：

此函数用于注册稍后尝试从文件中读取数据的回调函数。

原型：

void IFILE_Readable(IFile * pIFile, PFNNOTIFY pfn, void * pUser)

参数：

pIFile | 指向要为其注册回调函数的 IFile 接口对象的指针。
pfn | 回调函数的地址。
pUser | 调用回调函数时传递给它的用户定义数据。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IFILE_Cancel()

返回函数列表

IFILE_Release()

说明：

此函数用于减少 IFile 接口对象的引用计数。 如果引用计数为 0（零），则将关闭与 IFile 接口对象关联的文件。

原型：

uint32 IFILE_Release(IFile * pIFile)

参数：

pIFile
指向 IFile 接口对象的指针。

返回值：

已减少的对象引用计数。

如果该对象已被释放，且不再有效，则返回 0（零）。

备注：

无

另请参阅：

IFILEMGR_OpenFile()

IFILE_AddRef()

返回函数列表

IFILE_Seek()

说明：

此函数用于将 IFile 接口对象的文件指针从指定起点移动一段给定的距离。

原型：

uint32 IFILE_Seek
(
IFile * pIFile,
FileSeekType seekType,
int32 moveDistance
)

参数：

pIFile | 指向 IFile 接口对象的指针。
seekType | [_SEEK_CURRENT|_SEEK_START|_SEEK_END].
moveDistance | 要移动的距离。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

在特殊情况下，即定位类型为 _SEEK_CURRENT 且移动距离为 0（零）时，将返回当前文件指针的位置。

备注：

指定起点 (FileSeekType) 有三种值：

_SEEK_CURRENT

_SEEK_START

_SEEK_END

您可以指定正、负方向（值）的移动距离。 例如，从文件末尾 (_SEEK_END) 开始定位时使用负方向。 如果定位类型为 _SEEK_CURRENT，且移动距离为 0（零），此函数即变成识别操作，返回文件指针的当前位置； 如果是其它情况，文件指针将从指定的起点移动一段给定的距离。 如果文件的打开模式为 _OFM_READ，并且从指定起点的移动距离在文件边界范围内，此操作便会成功。 有关文件打开模式的详细信息，请参阅 IFILEMGR_OpenFile() 函数说明。 如果文件以 _OFM_READWRITE 模式打开，并且移动距离指向文件开始之前的位置，则此操作将失败。 如果从指定起点移动的距离超出了文件的结尾，则文件大小将从定位起点扩展到移至的位置。

例如：

用 READWRITE 模式创建一个文件，其大小为 40 字节。 如果调用定位类型为 _SEEK_START 的 IFILE_Seek() 函数，且移动距离为 120，将会使文件的大小增加到 120 字节，而文件指针会指向文件的末尾。

另请参阅：

IFILEMGR_OpenFile()

返回函数列表

IFILE_SetCacheSize()

说明：

设置文件缓存操作大小的函数。 这允许调用程序有选择地缓冲文件访问，
以提高性能。

原型：

int32 IFILE_SetCacheSize(IFile * pIFile, int32 nSize)

参数：

pIFile
指向 IFile 接口对象的指针
nSize
缓存的大小。
  • SCS_DEFAULT -使用由 OEM 指定的默认文件缓存大小
  • SCS_MIN -由 OEM 设置的最小缓存大小
  • SCS_MAX -由 OEM 设置的最大缓存大小
  • SCS_BEST -使用介于 OEM 指定的最大和最小之间的文件大小

返回值：

缓存大小，如果输入大小为 0，则释放缓存。

另请参阅：

无

返回函数列表

IFILE_Truncate()

说明：

此函数用于在 truncate_pos 参数指定的位置截断 IFile 接口对象指定的文件。

原型：

int IFILE_Truncate(IFile * pIFile, uint32 truncate_pos)

参数：

pIFile | 指向 IFile 接口对象的指针。
truncate_pos | 截断位置。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

要截断文件,需以读/写模式打开文件。

副作用：

文件截断后，文件指针将移至文件的开始位置。

另请参阅：

无

返回函数列表

IFILE_Write()

说明：

此函数用于将指定数量的字节写入打开的文件。 创建文件对象时，文件必须已由 IFileMgr 接口打开。

原型：

uint32 IFILE_Write
(
IFile * pIFile,
PACKED const void * pBuffer,
uint32 dwCount
)

参数：

pIFile | [in] | 指向 IFile 接口对象的指针。
pBuffer | [out] | 写入数据的缓冲区。
dwCount | [in] | 要写入的字节数。

返回值：

如果成功，则返回写入的字节数。

如果失败，则返回 0（零）。

备注：

要向文件写入数据，需以读/写模式打开文件。 有关打开文件的详细信息，请参阅 IFile 接口的 IFILEMGR_OpenFile() 函数。 从 IFile 接口对象中文件指针所在的位置开始写入字节。 您可以使用 IFILE_Seek() 函数重新确定文件指针在文件中的位置。

副作用：

写入操作结束后，IFile 接口对象的文件指针指向所写字节块的末尾。

另请参阅：

IFILEMGR_OpenFile()

IFILE_Read()

返回函数列表


IFileMgr 接口

IFileMgr 接口函数用于创建、删除和重命名文件/目录， 并且提供了获取相关信息的一些工具。 要创建 IFileMgr 接口的实例，您可以使用 AEECLSID_FILEMGR ClassID 调用 ISHELL_CreateInstance() 函数。 使用 IFileMgr 操作可以访问应用程序目录中的文件。
BREW AEE 还提供了一个允许在应用程序之间共享文件的共享应用程序目录。只要输入以共享目录名开头的目标路径即可访问所需的文件，共享目录名由 AEE.h 头文件中的 AEE_SHARED_DIR 常数定义（实际的共享目录名由设备制造商选择）。

BREW 中的文件和目录名不区分大小写。 这就意味着，如果为 IFileMgr 或其它任何与 BREW 文件相关的 API 指定了文件或目录名，文件名将全部变成小写。 例如，如果使用文件名 Foo.bar 调用 IFILEMGR_OpenFile()，则该文件将作为 foo.bar 打开。

设备上 BREW 所支持的文件名最大绝对长度（定义为 AEE_MAX_FILE_NAME）是 64。
但是，考虑到 BREW 安装路径，将模拟器上的文件名长度定义为 256。

注意：应用程序必须具有 PL_FILE 或 PL_SYSTEM 的优先级，才能创建文件和目录。 应用程序还必须具有 PL_SHARED_WRITE 或 PL_SYSTEM 优先级才能在共享应用程序目录中创建文件和目录。

和 IFILEMGR_EnumNext() 可以枚举给定目录中的所有目录或文件。 您还可以枚举带给定文件扩展名的所有文件。 首先，请调用 IFILEMGR_EnumInit() 函数指定一个目录以枚举其下的文件和目录。 随后每次调用 IFILEMGR_EnumNext() 都能获得关于所请求的某个目录或文件的信息，例如名称、大小、创建日期和属性。在枚举了所有指定文件或目录后，IFILEMGR_EnumNext() 将返回 FALSE。IFILEMGR_GetInfo() 可以返回按名称指定的特定文件或目录的相同信息，或者可以通过输入打开文件的 IFile 实例指针，
调用 IFILEMGR_GetInfo() 获取打开文件的这些信息。IFILEMGR_GetFreeSpace() 用于返回设备的文件系统上可用的空闲字节数。IFILEMGR_GetLastError() 用于返回 IFileMgr 函数最近检测到的错误（如果有）的错误代码。 通过该错误代码可以获取函数未能执行所请求任务的具体原因。IFILEMGR_Test() 用于检查指定的文件或目录是否存在。

IFILEMGR_MkDir() 用于创建新目录，该目录通过与调用该函数的小程序目录相关的名称和路径来指定。IFILEMGR_RmDir() 用于删除目录（首先必须删除要删除目录下的所有文件和
目录）。

IFILEMGR_RmDir() 用于创建新文件，或打开现有文件以进行读取或写入操作。 该文件通过与小程序目录相关的名称和路径指定。 IFILEMGR_OpenFile() 返回已打开文件的 IFile 实例指针。 您可以在 IFile 接口用于读写文件内容的函数中输入该指针。 通过将该指针作为参数调用 IFILEMGR_Release()，可以关闭打开的文件。IFILEMGR_Rename() 用于重命名文件，IFILEMGR_Remove() 用于删除文件。 在重命名或删除文件之前，必须先关闭文件；如果多次打开文件，则每次打开后都要执行相应的关闭操作，这样才能继续重命名或删除操作。

使用 IFileMgr 接口中的函数

  1. 调用 ISHELL_CreateInstance() 创建 IFileMgr 接口实例。
  2. 调用上述函数获取有关应用程序目录中文件和目录的信息，或者确定文件系统中可用的空闲空间。
  3. 调用 IFILEMGR_MkDir() 和 IFILEMGR_RmDir() 创建和删除目录，调用 IFILEMGR_OpenFile()、IFILEMGR_Rename() 和 IFILEMGR_Remove() 创建、重命名或删除个别文件。

读取或修改文件内容

  1. 调用 IFILEMGR_OpenFile() 函数打开要读取或写入的文件。
  2. 调用 IFile 接口中的函数访问文件内容。
  3. 访问结束后，调用 IFILE_Release() 关闭文件。
  4. 如果不再需要 IFileMgr 接口实例，则调用 IFILEMGR_Release()。

要包含的头文件列表

需要以下头文件：

AEEFILE.h

函数列表

此接口的函数包括：

IFILEMGR_AddRef()

IFILEMGR_EnumInit()

IFILEMGR_EnumNext()

IFILEMGR_EnumNextEx()

IFILEMGR_GetFileUseInfo()

IFILEMGR_GetFreeSpace()

IFILEMGR_GetInfo()

IFILEMGR_GetInfoEx()

IFILEMGR_GetLastError()

IFILEMGR_MkDir()

IFILEMGR_OpenFile()

IFILEMGR_Release()

IFILEMGR_Remove()

IFILEMGR_Rename()

IFILEMGR_RmDir()

IFILEMGR_SetDescription()

IFILEMGR_Test()

IFILEMGR_UnUse()

IFILEMGR_Use()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IFILEMGR_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IFILEMGR_Release()

返回函数列表

IFILEMGR_EnumInit()

说明：

此函数用于初始化 IFileMgr 接口对象，以便对指定目录下的文件或目录交互执行 IFILEMGR_EnumNext() 操作。

原型：

int IFILEMGR_EnumInit
(
IFileMgr * pIFileMgr,
const char * pszDir,
boolean bDirs
)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszDir | 包含根目录名且以 NULL 结尾的字符串。""是有效的文件名，指应用程序的根目录。
bDirs | 枚举类型，可取以下值： TRUE： 仅枚举目录。 FALSE： 仅枚举文件。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

无

另请参阅：

IFILEMGR_EnumNext()

返回函数列表

IFILEMGR_EnumNext()

说明：

此函数用于返回 IFileMgr 接口对象指定根目录中下一个文件或目录的文件信息。

原型：

boolean IFILEMGR_EnumNext(IFileMgr * pIFileMgr, FileInfo * pInfo)

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针。
pInfo | [out] | 文件信息占位符。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

此函数获取的文件信息包含文件属性、文件创建日期和文件大小。 MOD 和 SIG 文件是应用程序的隐藏文件，调用 IFILEMGR_EnumNext() 不会使它们作为枚举部分返回。

另请参阅：

FileInfo

IFILEMGR_EnumInit()

返回函数列表

IFILEMGR_EnumNextEx()

说明：

该函数用于返回 IFileMgr 接口对象指定根目录中下一个文件或目录的扩展信息。

原型：

boolean IFILEMGR_EnumNext(IFileMgr * pIFileMgr, AEEFileInfoEx * pInfo)

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针
pInfo | [out] | 扩展文件信息占位符

返回值：

如果成功，则返回 TRUE

如果失败，则返回 FALSE

备注：

无

另请参阅：

IFILEMGR_EnumInit()

FileInfo

返回函数列表

IFILEMGR_GetFileUseInfo()

说明：

此函数用于获取模块的文件使用信息。

原型：

int IFILEMGR_GetFileUseInfo(IFileMgr * pfm, AEEFileUseInfo * pfu);

参数：

pfm | [in] | 指向 IFileMgr 接口对象的指针
pfu | [out] | 文件使用信息占位符

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

无

另请参阅：

AEEFileUseInfo

返回函数列表

IFILEMGR_GetFreeSpace()

说明：

此函数用于获取文件系统中当前可用的空闲字节数。 如果传送的参数 pdwTotal 非 NULL，则此函数会将 pdwTotal 初始化为文件系统的总空间。

原型：

uint32 IFileMgr_GetFreeSpace(IFileMgr * pIFileMgr, uint32 * pdwTotal)

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针。
pdwTotal | [in/out] | 文件系统总空间的占位符。

返回值：

如果成功，则返回当前可用的文件系统空间的字节数。

如果失败，则返回 0（零）。

备注：

无

另请参阅：

无

返回函数列表

IFILEMGR_GetInfo()

说明：

此函数用于获取通过文件名标识的文件的信息。 此函数获取的文件信息包含文件属性、文件创建日期和文件大小。

原型：

int IFILEMGR_GetInfo
(
IFileMgr * pIFileMgr,
const char * pszName,
FileInfo * pInfo
)

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针。
pszName | [in] | 包含文件名且以 NULL 结尾的字符串。“”是有效的文件名，指应用程序的根目录。
pInfo | [out] | 文件信息占位符。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

无

另请参阅：

FileInfo

IFILE_GetInfoEx()

返回函数列表

IFILEMGR_GetInfoEx()

说明：

此函数用于获取由文件名确定的文件的扩展信息。 扩展文件信息包含于 AEEFileInfoEx 结构中。

原型：

int IFILEMGR_GetInfoEx
(
IFileMgr * pIFileMgr,
const char * pszName,
AEEFileInfoEx * pi
);

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针。
pszName | [in] | 以 NULL 结尾且包含文件名的字符串
pi | [out] | 扩展文件信息占位符

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

无

另请参阅：

AEEFileInfoEx

IFILE_GetInfoEx()

返回函数列表

IFILEMGR_GetLastError()

说明：

在小程序执行的文件操作失败，并且该小程序需要了解失败原因时，可调用此函数。

原型：

int IFILEMGR_GetLastError(IFileMgr * pIFileMgr)

参数：

pIFileMgr
指向 IFileMgr 接口对象的指针。

返回值：

如果上次文件操作成功，则返回 SUCCESS。

如果失败，则可能出现以下错误之一：

EFILEEXISTS： 文件存在。

EFILENOEXISTS： 文件不存在。

EDIRNOTEMPTY： 目录非空。

EBADFILENAME： 错误的文件名。

EBADSEEKPOS： 错误的定位位置。

EFILEEOF： 文件结束。

EFSFULL： 文件系统已满。

EFILEOPEN： 文件已打开。

EBADPARM： 无效参数。

i

备注：

无

另请参阅：

无

返回函数列表

IFILEMGR_MkDir()

说明：

此函数用于创建指定目录名的目录。

原型：

int IFILEMGR_MkDir(IFileMgr * pIFileMgr, const char * pszDir)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszDir | 包含目录名且以 NULL 结尾的字符串。

返回值：

如果成功创建文件或文件已经存在，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

无

另请参阅：

IFILEMGR_RmDir()

返回函数列表

IFILEMGR_OpenFile()

说明：

此函数用于以指定方式打开文件。

原型：

IFile * IFILEMGR_OpenFile
(
IFileMgr * pIFileMgr,
const char * pszFile,
OpenFile mode
)

参数：

pIFileMgr
指向 IFileMgr 接口对象的指针。
pszFile
以 NULL 结尾且包含文件名的字符串。
mode
文件的打开方式，可取以下值：
  • _OFM_READ： 以只读方式打开文件，不会创建文件。
  • _OFM_READWRITE： 以读/写方式打开文件，不会创建文件。
  • _OFM_APPEND： 与 _OFM_READWRITE 相同；或者与 FM_READWRITE 相同，但将文件指针设置到文件末尾（取决于
    II-a 的应答）。
  • _OFM_CREATE： 以读/写方式创建新文件。 如果此文件已经存在，则生成错误，并且不打开文件。

返回值：

如果成功，则返回指向已打开文件 IFile 接口对象的指针。

如果函数调用失败，则返回 NULL。

备注：

如果 pszFile 包含创建文件的路径，并且调用程序有权在指定目录中创建文件，则将在此路径（如果有）中创建文件和不存在的目录。 所创建的文件可执行读/写访问。

如果 pszFile 包含文件所在的路径，并且调用程序有权在指定目录（如果此目录存在）中打开文件，则可以打开该文件。 目录可以通过 IFILEMGR_MkDir() 创建。

副作用：

如果以 _OFM_APPEND 方式打开文件，则文件指针将移至文件结尾。

另请参阅：

IFILEMGR_MkDir()

返回函数列表

IFILEMGR_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IFILEMGR_AddRef()

返回函数列表

IFILEMGR_Remove()

说明：

此函数用于删除通过指定文件名标识的文件。

原型：

int IFILEMGR_Remove(IFileMgr * pIFileMgr, const char * pszName)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszName | 包含要删除文件的名称且以 NULL 结尾的字符串。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

删除文件前需先关闭文件 请使用 IFILE_Release() 关闭文件。

另请参阅：

无

返回函数列表

IFILEMGR_Rename()

说明：

此函数用于将文件从源名称重命名为目标名称。

原型：

int IFILEMGR_Rename
(
IFileMgr * pIFileMgr,
const char * pszSrc,
const char * pszDest
)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszSrc | 要重命名的源文件。
pszDest | 目标文件。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

如果返回 EFAILED，请使用 IFILEMGR_GetLastError() 获取详细的出错信息。

另请参阅：

IFILEMGR_EnumNext()

返回函数列表

IFILEMGR_RmDir()

说明：

此函数用于删除通过指定目录名标识的目录。

原型：

int IFILEMGR_RmDir(IFileMgr * pIFileMgr, const char * pszDir)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszDir | 包含目录名且以 NULL 结尾的字符串。

返回值：

如果成功，则返回 SUCCESS。

如果失败，则返回 EFAILED。

备注：

如果目录包含文件或子目录，请在调用此函数之前先将其删除，否则此调用将失败，并且无法删除该目录。

另请参阅：

IFILEMGR_MkDir()

返回函数列表

IFILEMGR_SetDescription()

说明：

此函数用于设置属于扩展文件信息一部分的文件说明。

原型：

int IFILEMGR_SetDescription
(
IFileMgr * pfm,
const char * pszName,
AECHAR * pszDesc
);

参数：

pfm | [in] | 指向 IFileMgr 接口对象的指针
pszName | [in] | 以 NULL 结尾且包含文件名的字符串
pszDesc | [in] | 包含说明的宽字符串

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

IFILEMGR_SetDescription 只显示共享目录中文件的文本说明。 如果 IFILEMGR_SetDescription 中指定的文件在应用程序目录中，则不返回或显示任何
说明。

另请参阅：

IFILEMGR_EnumInit()

FileInfo

返回函数列表

IFILEMGR_Test()

说明：

此函数用于测试指定文件或目录是否存在。

原型：

int IFILEMGR_Test(IFileMgr * pIFileMgr, const char * pszName)

参数：

pIFileMgr | 指向 IFileMgr 接口对象的指针。
pszName | 包含文件或目录名且以 NULL 结尾的字符串。 ìì是有效的文件名， 指应用程序的根目录。

返回值：

如果指定的文件或目录存在，则返回 SUCCESS。

否则，返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

IFILEMGR_UnUse()

说明：

此函数用于将调用应用程序的类 ID 从使用指定文件的类列表中删除。 当最后一个应用程序指示不再使用该文件或调用 IFILEMGR_Remove() 时，所指定的文件将被删除。

原型：

int IFILEMGR_Use(IFileMgr * pfm, const char * pszName);

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针
pszName | [in] | 以 NULL 结尾且包含文件名的字符串

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

当前已跟踪共享目录中的文件。 此 API 只应用于共享目录中的文件。

另请参阅：

IFILEMGR_Use()

IFILEMGR_GetInfoEx()

AEEFileInfoEx

返回函数列表

IFILEMGR_Use()

说明：

此函数用于将调用应用程序的类 ID 添加到使用指定文件的类列表中。 直到最后一个应用程序指示不再使用该文件或调用 IFILEMGR_Remove() 时，所指定的文件才会被删除。

原型：

int IFILEMGR_Use(IFileMgr * pfm, const char * pszName);

参数：

pIFileMgr | [in] | 指向 IFileMgr 接口对象的指针
pszName | [in] | 以 NULL 结尾且包含文件名的字符串

返回值：

如果成功，则返回 SUCCESS

如果失败，则返回 EFAILED

如果内存不足，则返回 ENOMEMORY

备注：

当前已跟踪共享目录中的文件。 此 API 只应用于共享目录中的文件。

另请参阅：

IFILEMGR_UnUse()

IFILEMGR_GetInfoEx()

AEEFileInfoEx

返回函数列表


IFont 接口

此接口提供绘制和度量文本的函数。应用程序通常不会直接调用 IFont 成员函数。IDisplay 提供了一个更为友好且方便的文本绘制接口，并支持系统颜色和剪切状态，以及与绘制文本相关的多种功能，例如下划线、居中、边框和清除背景。IFont 函数对于参数的要求更加严格，而在默认值时缺少灵活性。由于 IDisplay 在 IFont 基础上编译并且任何 IFont 均可传递到 IDisplay 供其管理，因此直接使用 IFont 不会增加功能。

IFont 接口具有多种实现。有些 IFont 类可能只与某个特定的 IBitmap 类一起使用，而其它的则可以和任何支持 1 位 blit 的 IBitmap 一起使用。默认情况下，IDisplay 使用 OEM 提供的 IFont 对象。这些字体对象的大小和外观可能因手持设备而异，并且有些可能不支持后台屏幕位图。

要包含的头文件列表

需要以下头文件：

AEEFont.h

函数列表

此接口的函数包括：

IFONT_AddRef()

IFONT_DrawText()

IFONT_GetFontInfo()

IFONT_MeasureText()

IFONT_QueryInterface()

IFONT_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IFONT_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.IFONT_Release()

返回函数列表

IFONT_DrawText()

说明：

此函数用于在位图内绘制文本。x 和 y 参数说明最左侧字符单元的左上角位置。

绘制操作限制于矩形 *prcClip 内。落在该矩形以外（或位图界限以外）的所有文本均不予绘制。剪切影响是否绘制像素，而不会影响绘制的位置。

IFONT_DrawText() 的所有参数均应有效。同 IDisplay 一样，无效或特殊值不会解释为具有特殊含义。dwFlag 参数由一组选择特定选项的位标记组成。这些值为 IDISPLAY_DrawText() 定义，但仅支持 IDF_TEXT_TRANSPARENT。如果指定 IDF_TEXT_TRANSPARENT，则只会在先前占据目标矩形的所有像素上绘制前景部分
（即图形显示字符）；否则，将完整绘制每个字符单元（前景和背景像素）。

原型：

int IFONT_DrawText
(
IFont *pIFont,
IBitmap *pDst,
int x,
int y,
const AECHAR *pcText,
int nChars,
NativeColor foreground,
NativeColor background,
const AEERect *prcClip,
uint32 dwFlags
)

参数：

pIFont | [in] | 指向 IFont 接口的指针。
pDst | [in]/[out] | 指向目标 IBitmap 的指针。
x | [in] | 文本字符串的 X 坐标。
y | [in] | 文本字符串的 Y 坐标。
pcText | [in] | 要绘制的文本字符串。
nChars | [in] | 文本字符串长度。如果为 -1，则此函数将自动计算该长度。
foreground | [in] | 绘制文本的颜色。
background | [in] | 绘制背景的颜色。
prcClip | [in] | 必须在其中绘制文本字符串的剪切矩形。
dwFlags | [in] | 指示文本显示外观的属性位图。

返回值：

如果成功，则返回 SUCCESS。

否则，返回错误代码。

如果底层 IBitmap 不支持字体需要的操作，则返回 EUNSUPPORTED。

其它实现特定的错误代码。

备注：

x 和 y 为负值是合法的，指示起始位置位于位图左侧或顶部以上。在这种情况下，将绘制扩展到位图以内（和 *prcClip 以内）的文本部分。

如果 *prcClip 的宽度或高度为负值，将不绘制任何内容。

前景和背景颜色值为 NativeColor 值，而不是 RGBVAL。通过调用目标位图的 IBITMAP_RGBToNative() 可以获取它们。

另请参阅：

NativeColor

IBITMAP_RGBToNative()

IFONT_MeasureText()

返回函数列表

IFONT_GetFontInfo()

说明：

此函数用于将字体信息填入 AEEFontInfo 结构。返回信息为当前的上下行字母值。

传递结构大小是为了保证向后兼容性。该实现最多只能将结构填写到指定大小。如果大小超过 sizeof(AEEFontInfo)，则函数将返回 EUNSUPPORTED。

原型：

int IFONT_GetFontInfo(IFont * pIFont, AEEFontInfo * pinfo, int nSize)

参数：

pIFont | [in] | 指向 IFont 接口的指针。
pinfo | [out] | 指向要填写的 AEEFontInfo 结构的指针。
nSize | [in] | 要填写的结构大小。

返回值：

如果已获取字体信息，则返回 SUCCESS。

如果不支持由 sizeof(AEEFontInfo) 确定的版本，则返回 EUNSUPPORTED。

备注：

如果传递了有效的 pinfo 指针，且 nSize 等于 sizeof(AEEFontInfo)，
则 IFONT_GetInfo() 将始终成功。

另请参阅：

AEEFontInfo

IFONT_MeasureText()

返回函数列表

IFONT_MeasureText()

说明：

此函数用于度量文本的宽度。它计算给定的最大宽度所能容纳的字符数，以及这些字符占用的像素数。IFONT_MeasureText() 的所有参数必须有效。无效值或特殊值不会解释为具有特殊含义。

原型：

int IFONT_MeasureText
(
IFont *pIFont,
const AECHAR *pcText,
int nChars,
int nMaxWidth,
int *pnFits,
int *pnPixels
)

参数：

pIFont | [in] | 指向 IFont 接口的指针。
pcText | [in] | 要以像素为单位进行度量的文本字符串。
nChars | [in] | 文本字符串长度。如果为-1，则此函数将自动计算该长度。
nMaxWidth | [in] | 最大可用屏幕宽度（以像素为单位）。
pnFits | [out] | 给定可用宽度的屏幕中可以容纳的字符数。
pnPixels | [out] | 可用空间中可以容纳的文本字符串总宽度（以像素为单位）。

返回值：

SUCCESS

备注：

无

另请参阅：

IFONT_GetFontInfo()

返回函数列表

IFONT_QueryInterface()

说明：

此函数检索指向符合指定类 ID 定义的接口的指针。它可用于查询扩展功能，如未来版本或专有扩展。

如果查询成功，则返回接口实例。调用者将在未来的某个时刻负责调用 Release()。 返回指针不是接口指针的情况除外。 在这种情况下，内存与正被查询的对象具有相同的使用期，所返回的指针将不用于释放对象。

原型：

int IFONT_QueryInterface(IFont * pIFont, AEECLSID id, void ** p)

参数：

pIFont | [in] | 指向 IFont 接口的指针。
id | [in] | 标识要查询的实体（接口或数据）的全局唯一 ID。
p | [out] | 指向要检索的数据或接口的指针。如果传递回来的值为 NULL， 则表示所查询的接口或数据不存在。

返回值：

如果成功，则返回 SUCCESS，

如果不支持类 ID，则返回 ECLASSNOTSUPPORT

备注：

如果失败，则 QueryInterface() 必须将 *pIFont 设置为 NULL。

另请参阅：

无

返回函数列表

IFONT_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IFONT_AddRef()

返回函数列表


IGetLine 接口

IGetLine 接口提供用于行分析数据的函数。IGETLINE_LineComplete() 测试 GetLine 退出代码，并在接收到完整行时（例如行没有因缓冲区限制或错误而截断）返回 TRUE。

IGETLINE_LineComplete(code)((code) >= 0)

IGETLINE_EOLSize() 提供终止 GetLine 返回的行，并给出结果代码的 EOL 序列的长度。 GetLine 在返回行之前，会先删除 EOL 序列。 可能的取值为：

2 | CRLF seen。
1 | 单个 CR 或 LF seen。
0 | 行以 END、ERROR、WAIT 或 FULL 退出代码结束。

IGETLINE_EOLSize(code)((code) > 0 ? ((code) >> 1): 0)

在代码指示源不能返回更多数据时，IGETLINE_Exhausted() 将返回 TRUE。

要包含的头文件列表

需要以下头文件：

AEESource.h

函数列表

此接口的函数包括：

IGETLINE_AddRef()

IGETLINE_Advance()

IGETLINE_EOLSize()

IGETLINE_Exhausted()

IGETLINE_GetLine()

IGETLINE_LineComplete()

IGETLINE_Peek()

IGETLINE_Peekable()

IGETLINE_QueryInterface()

IGETLINE_Read()

IGETLINE_Readable()

IGETLINE_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IGETLINE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.IGETLINE_Release()

返回函数列表

IGETLINE_Advance()

说明：

此函数可以使取数指针在缓冲区中前进或后退。

原型：

void IGETLINE_Advance(IGetLine * pIGetLine, int32 cbAdvance)

参数：

pIGetLine | 指向 IGetLine 接口对象的指针。
cbAdvance | 要前进（或后退，如果值为负）的字节数。

返回值：

无

备注：

大于缓冲字符数的字节数可安全前进至所有缓冲字符的末端。

另请参阅：

无

返回函数列表

IGETLINE_EOLSize()

说明：

此宏用于返回终止了 GetLine 返回的行，并且给出结果代码的 EOL 序列的长度。 GetLine 在返回行之前，会先删除 EOL 序列。

定义：

IGETLINE_EOLSize(code)((code) > 0 ? ((code) >> 1): 0)

参数：

code
从 Read()、Peek() 或 GetLine() 返回的值

返回值：

如果为 CRLF seen，则返回 2。

如果为单个 CR 或 LF seen，则返回 1。

如果行以 END、ERROR、WAIT 或 FULL 退出代码结束，则返回 0。

备注：

无

另请参阅：

IGETLINE_GetLine()

返回函数列表

IGETLINE_Exhausted()

说明：

此宏用于确定 ISource、IPeek 或 IGetLine 是否用尽数据。

原型：

IGETLINE_Exhausted(code)((unsigned) - (code) < 2U)

参数：

code
从 Read()、Peek() 或 GetLine() 返回的值

返回值：

如果源数据已用尽（无更多的数据），则返回 TRUE。

否则，返回 FALSE。

备注：

在 Peek() 和 GetLine() 情况下，仍有可能返回数据。 请检查 _Peek() 的 cbAvailable 参数或 GetLine 数据结构的 nLen 字段。

另请参阅：

无

返回函数列表

IGETLINE_GetLine()

说明：

此函数用于从数据源中获取文本的下一个逻辑行。 逻辑行是指以行终止符字符序列（EOL）结束的字节序列。 当前支持的行终止符为 CR 和 CRLF。 此函数还可以返回未正确终止的行，以及在逻辑行长度超出可用缓冲区大小时返回部分行。 返回代码将指明返回的原因，因此必要时可以重建输入流的实际二进制形式。

IGETLINE_GetLine() 为同步调用。 它将返回可用的即时信息。 如果需要缓冲更多数据才能确定下一行将在何处结束，则它将返回 IGETLINE_WAIT，调用程序必须稍后重试。 接收返回代码 IGETLINE_WAIT 后，调用程序将使用 IGETLINE_Peekable() 成员函数获知何时应重试 IGETLINE_GetLine()。 在其它所有情况下，无需等待 IGETLINE_Peekable() 即应调用 IGETLINE_GetLine()，以便检查所有的缓冲数据并确定调用程序是否应等待 IGETLINE_Peekable()。

原型：

int IGETLINE_GetLine
(
IGetLine * pIGetLine,
GetLine * pline,
int32 nTypeEOL
)

参数：

pIGetLine
指向 IGetLine 接口对象的指针。
pline
指向用于保存结果的结构的指针。 退出时：
pline->ps2 = 指向行数据（以零结尾）开头的指针。
pline->nLen = 行中的字符数。
pline->bLeftover = TRUE，如果返回的文本为前一截断行的后续部分。 换言之，上一个返回代码为 IGETLINE_FULL
（忽略 IGETLINE_WAIT 返回代码）。
*pline 说明的文本不包含任何 EOL 字符。 如果行是以 EOL 字符序列结束，则 GetLine 将在初始的 EOL 字符上写入 NULL 字符，以确保零
终止。
如果行中不包含 NULL 字符，则 nLen 与 strlen(ps2) 相同。 GetLine() 不限定行的内容，因此返回的行中可能包含二进制数据（当然，有效 EOL 序列除外）。
调用程序可以修改所有行数据（包括 EOL 字符），因此必要时可重建原始二进制形式（包括 EOL 字符）。
nTypeEOL
指定应识别的 EOL 序列：
  • IGETLINE_CRLF = 仅 CRLF 序列终止行。
  • IGETLINE_LF = CRLF 或单个 LF 终止行。
  • IGETLINE_CR = CRLF、单个 LF 或单个 CR 终止行。 此选项不完全支持，它相当于 IGETLINE_LF。]

返回值：

以下退出代码之一，说明返回 GetLine 的原因：

如果该行尚未完成，则返回 IGETLINE_WAIT；稍后重试。

    • 在这种情况下，*pline 将说明可用数据（未完成行），但数据不会被处理。 调用程序应使用 IGETLINE_Peekable() 调度下一个 IGETLINE_GetLine() 调用。
    • 在其它情况下，*pline 中说明的数据将全部用尽，因而不再使用 IGETLINE_Peekable()，而可以调用 IGETLINE_Readable() 或 ISHELL_Resume()。

      • 如果行以双字符 EOL (CRLF) 结束，则返回 IGETLINE_CRLF。

      如果行以单字符 EOL (CR) [未实现] 结束，则返回 IGETLINE_CR。

      如果行以单字符 EOL (LF) 结束，则返回 IGETLINE_LF。

      如果行因数据流结束而结束，则返回 IGETLINE_END；无 EOL seen。

      如果行因错误结束，则返回 IGETLINE_ERROR；无 EOL seen。

      如果数据受缓冲区大小限制，则返回 IGETLINE_FULL；无 EOL seen；
      后有余数。

备注：

在 IGETLINE_WAIT 的情况下，未完成行的内容（如果有）将不被处理。 这表示后续的 IGETLINE_Read()、IGETLINE_Peek() 或 IGETLINE_GetLine() 调用将返回该数据。

在其它所有情况下，数据将被用尽。 这表示 IGETLINE_GetLine() 将把读指针推进到行内容之后（包括行结尾），因此后续的 IGETLINE_Read()、IGETLINE_Peek() 或 IGETLINE_GetLine() 调用将返回该行以后的数据。

只有在无更多数据时，才会返回 IGETLINE_END 或 IGETLINE_ERROR。此时可以方便地使用 IGETLINE_Exhausted()。

IGETLINE_UngetLine() 用于将数据流恢复至行用尽之前的实际二进制状态。 这主要是为了实现 HTTP 0.9 的兼容性。传递给 IGETLINE_UngetLine() 的长度值必须与上次调用 IGETLINE_GetLine() 所返回的长度值相同，并且其间不得调用其它成员函数，
否则结果将会不确定。

IGETLINE_LineComplete(code) 可用于正常情况下的测试，其中行以有效的 EOL 序列或数据流结束。 对于

{IGETLINE_END, _CR, _LF, _CRLF}，它将返回 TRUE。

在 IGETLINE_WAIT 的情况下，IGETLINE_Readable() 不提供何时重试 IGETLINE_GetLine() 的相应通知。IGETLINE_Readable() 指示 IGETLINE_Read() 已就绪，并由此通知存在未缓冲*或*已缓冲的数据。 只要存在缓冲数据，IGETLINE_Read() 都将成功，而 GetLine() 在检查过缓冲数据并确定这些数据不足完成一行的情况下却不会成功。 在 IGETLINE_WAIT 结果之后调用 IGETLINE_Readable() 可能导致无意义的重复回调，阻止应用程序正确地让出时间给其它应用程序。 IGETLINE_Peekable() 通知存在未缓冲的新数据，可以正确地让出时间直至需要再次调用 IGETLINE_GetLine()。
在首次调用 IGETLINE_GetLine() 之前，或者非 IGETLINE_WAIT 结果代码之后，
可以使用 IGETLINE_Readable() 或 ISHELL_Resume() 调度 IGETLINE_GetLine()
调用。 这两个函数中都允许 IGETLINE_GetLine() 在等待之前先检查所有缓冲数据。

另请参阅：

GetLine

返回函数列表

IGETLINE_LineComplete()

说明：

此宏用于确定所返回的行是否完整。

定义：

IGETLINE_LineComplete(code)((code) >= 0)

参数：

code
_GetLine() 的返回值。

返回值：

如果收到完整的行（如该行未因缓冲区限制或错误而被截断），则返回 TRUE。

否则，返回 FALSE。

备注：

同时还会设置 GetLine 结构的 bTruncated 字段。

另请参阅：

IGETLINE_GetLine()

返回函数列表

IGETLINE_Peek()

说明：

此函数用于返回指向缓冲数据的指针，并可随意尝试将更多的数据读入缓冲区。

原型：

char * IGETLINE_Peek
(
IGetLine * pIGetLine,
int32 cbWanted,
int32 * pcbAvailable,
int32 * pnCode
)

参数：

pIGetLine | [in] | 指向 IGetLine 接口对象的指针。
cbWanted | [in] | 指定的字节数。 如果缓冲区中已停留多个字节，Peek() 不会执行额外的工作，否则它将尝试从网络或其它来源复制更多的数据。 传递 0 以快速查询当前缓冲区状态。 IGETLINE_PEEKMAX 表示尽可能多地返回。
pcbAvailable | [out] | 缓冲数据的大小。
pnCode | [out] | 说明返回值以外的数据的可用性：
 |  | IGETLINE_END | 无更多数据（数据流中遇到 END）。
 |  | IGETLINE_ERROR | 无更多数据（数据流中遇到 ERROR）。
 |  | IGETLINE_FULL | 数据受到缓冲区大小限制。 必须处理完缓冲数据才能获取新数据。
 |  | IGETLINE_WAIT | 再次调用之前，必须等待 IGETLINE_Peekable()()。 轮询数据源，当前无可用数据。
 |  | IGETLINE_UNK | 请求量小于缓冲量。 使用更大的 cbWanted 再次调用。 未轮询数据源。

返回值：

缓冲数据的起始字符。

备注：

无

另请参阅：

无

返回函数列表

IGETLINE_Peekable()

说明：

当有更多的未缓冲数据可用时，可以使用此函数调用回调。 调用回调之后，IGETLINE_Peek() 可以返回比以前更多的数据。

原型：

void IGETLINE_Peekable(IGetLine * pIGetLine, AEECallback * pcb)

参数：

pIGetLine | 指向 IGetLine 接口对象的指针。
pcb | 在 ISource 可读时，指向调用位置的指针。

返回值：

无

备注：

存在缓冲数据并不表示要立即进行回调。 请确保仅在确定当前缓冲数据不足以继续时才调用此函数。

另请参阅：

无

返回函数列表

IGETLINE_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IGETLINE_QueryInterface
(
IGetLine * pIGetLine,
AEECLSID idReq,
void * * ppo
)

参数：

pIGetLine | [in] | 指向 IGetLine 接口对象的指针。
idReq | [in] | 对象显露的被请求的 ClassID。
ppo | [out] | 返回的对象。 由此函数填充。

返回值：

如果找到接口，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT。

备注：

如果 *ppo 为接口指针，则 *ppo 中的指针将被设置为新接口（同时增加引用计数），
如果对象不支持 ClassID，则将被设置为 NULL。

如果 *ppo 为数据结构指针，则 *ppo 将被设置为 classID 代表的内部数据，如果对象不支持 classID，则将被设置为 NULL。

另请参阅：

AEECLSID 列表

返回函数列表

IGETLINE_Read()

说明：

此函数用于将源数据流中的字节复制到指定缓冲区。 复制的所有字节均“用尽”（即，“读指针”前置）。

原型：

int IGETLINE_Read(IGetLine * pIGetLine, char * pcBuf, int32 cbBuf)

参数：

pIGetLine | 指向 IGetLine 接口对象的指针。
pcBuf | 指向接收所读字节的缓冲区的指针。
cbBuf | sizeof(pc)。

返回值：

如果成功，则返回读取的字节数。

如果失败，则返回以下值之一：

对等端正常切断连接（无更多数据），则返回 ISOURCE_END。

遇到错误（无更多数据），则返回 ISOURCE_ERROR。

此时无可用数据，则返回 ISOURCE_WAIT；调用 Readable() 以等待。

备注：

无

另请参阅：

无

返回函数列表

IGETLINE_Readable()

说明：

此函数用于在 IGETLINE_Read() 返回非 IGETLINE_WAIT 的其它值时调度或取消
回调。

原型：

void IGETLINE_Readable
(
IGetLine * pIGetLine,
AEECallback *pcb
)

参数：

pIGetLine | 指向 IGetLine 接口对象的指针。
pcb | 当 ISource 可读时，指向调用位置的指针。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

返回函数列表

IGETLINE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IGETLINE_AddRef()

返回函数列表

IGETLINE_UngetLine()

说明：

此函数用于放弃（不获取）数据源中最后一个逻辑行的部分或全部，并替换数据流中的行终止符。

原型：

void IGETLINE_UngetLine(IGetLine *pIGetLine, int32 nLenUnused)

参数：

pIGetLine | 指向 IGetLine 接口对象的指针。
nLenUnused | 指定要放弃（不获取）的数据量（最大可达最后一行的长度）。 此数字必须小于或等于 GetLine 结构中最后一次调用 GetLine() 所填入的 nLen，例如，它*不得*包含行终止符的长度。

返回值：

无

备注：

在下次调用 IGETLINE_GetLine() 之前，IGETLINE_UngetLine() 只能使用一次。使用大于最后一行长度的数字调用 IGETLINE_UngetLine() 或两次调用 IGETLINE_UngetLine() 将导致未定义的行为。

另请参阅：

无

返回函数列表


IGraphics 接口

IGraphics 接口函数将 IDisplay 接口的绘制能力扩展到绘制更复杂的 2D 几何图元，
如圆和任意多边形。 IGraphics 接口还支持剪切和视图变换。 只有在调用 IGRAPHICS_Update() 或 IDISPLAY_Update() 之后，IGraphics 绘制操作才会在屏幕上得到更新。 请使用 IGRAPHICS_Update()，而不使用 IDISPLAY_Update()。 此接口的将来版本可以支持双缓冲，它允许程序直接在可以与当前屏幕交换内容的后台屏幕缓冲上执行绘制操作。


IGraphics 坐标系统

在 BREW AEE 中，所有坐标系统均以像素表示。 IGraphics 接口对世界坐标系统和屏幕坐标系统进行了区分。 在这两种坐标系统中，x 轴的正向都是自左向右延伸，y 轴的正向都是向下延伸。
世界坐标系统是开发者用来说明场景的逻辑坐标系统。 为方便起见，开发者可以任意选择世界坐标系统的原点。 屏幕坐标系统的原点则始终位于设备屏幕的左上角。 用于显示的世界坐标系统区域称为窗口（请注意与 Microsoft Windows 窗口的区别）。 屏幕上窗口映射至的区域称为视口。 窗口定义要查看的内容；视口定义要显示的位置。 由于此版本中 IGraphics 不支持按比例缩放，因此窗口和视口大小相同。 IGraphics 接口通过以下三个函数支持视图变换
（也称为窗口到视口的变换）： IGRAPHICS_SetViewport()、IGRAPHICS_Translate()和IGRAPHICS_Pan()。

IGRAPHICS_SetViewport() 用于在屏幕坐标系统中设置矩形区域（视口）。 此视口是所有 IGraphics 操作的显示区域。IGRAPHICS_GetViewport() 以屏幕坐标的方式返回当前视口。 默认情况下，整个屏幕就是 IGraphics 视口。
IGRAPHICS_Translate() 用于在世界坐标系统中移动窗口。 默认情况下，窗口的左上角位于世界坐标系统的原点 (0, 0)。
如果您不熟悉坐标系统以及与图形相关的其它术语，请阅读 Donald Hearn 和 M. Pauline Baker 合著的 Computer Graphics: C Version。


IGraphics 设置和获取函数

IGraphics 函数使用大量参数来确定在屏幕上绘制对象的方式。 设置参数值后，该值即应用于后续的所有绘制操作，直至更改参数。 IGraphics 接口中包含多个可以设置这些参数值的“设置”函数，以及可用于获取参数值的“获取”函数。 IGraphics 接口提供了以下“设置”函数：
  • IGRAPHICS_SetBackground() 用于设置在调用 IGRAPHICS_ClearRect() 和 IGRAPHICS_ClearViewport() 时使用的背景颜色。 在使用 AEE_GRAPHICS_CLEAR 标记组设置剪切区域时，也要用到该背景颜色。
  • IGRAPHICS_SetClip() 指定用于绘制的剪切区域。 绘制操作只能在由 AEEClip 结构定义的剪切区域内进行。
  • IGRAPHICS_SetColor() 用于设置前景颜色的值。 所有线条和图形边框都用该颜色绘制。
  • IGRAPHICS_SetFillColor() 用于设置填充封闭几何图形内部所用的颜色。
  • IGRAPHICS_SetFillMode() 用于设置填充模式。 如果填充模式为 TRUE，则封闭几何图元的内部将用当前填充色进行填充。 如果填充模式为 FALSE，则仅绘制几何图元的边框。
  • IGRAPHICS_SetPaintMode() 用于设置着色模式，该模式可以确定要绘制像素颜色与屏幕已有颜色的组合方式。 如果着色模式为 AEE_PAINT_COPY，新像素颜色将覆盖原有的屏幕颜色。 如果着色模式为 AEE_PAINT_XOR，屏幕显示的颜色将是新旧像素颜色的异或。
  • IGRAPHICS_SetPointSize() 用于设置屏幕绘制点的像素宽度。


IGraphics 绘制函数

以下 IGraphics 函数用于绘制各种 2D 几何图元：
  • IGRAPHICS_DrawPoint() 用于在指定的 x 和 y 坐标处绘制一个点。 该点的像素高度和宽度与当前点的大小相等。
  • IGRAPHICS_DrawLine() 用于在指定起点和终点之间绘制线段。
  • IGRAPHICS_DrawRect() 用于绘制矩形。 矩形由其左上角位置及其 x 和 y 轴正方向上的像素数目定义。
  • IGRAPHICS_DrawCircle() 用于绘制由圆心和半径定义的圆。
  • IGRAPHICS_DrawArc() 用于绘制作为圆周一部分的弧。 在此函数中要输入圆心、半径以及定义要显示圆周部分的起始角和终止角。
  • IGRAPHICS_DrawPie() 用于绘制作为圆周楔形部分的饼图。 饼图是一个从圆心到圆周的两条线所包围的区域。 在此函数中要输入圆心、半径和两条线的夹角。
  • IGRAPHICS_DrawEllipse() 用于绘制由中心点、长轴及短轴半径定义的椭圆。
    长轴必须与 x 轴或 y 轴平行。
  • IGRAPHICS_DrawPolygon() 用于绘制由一组顶点定义的多边形。
  • IGRAPHICS_DrawPolyline() 用于绘制由一系列点定义的折线。 此函数可绘制连接列表中相邻两个点的线段。
  • IGRAPHICS_DrawTriangle() 用于绘制由三个顶点坐标定义的三角形。
在 IGraphics 绘制函数中输入的值均以世界坐标系统为准。


其它 IGraphics 函数

  • IGRAPHICS_ClearRect() 可以通过在世界坐标系统的矩形区域中填充当前背景颜色来清除该区域。
  • IGRAPHICS_ClearViewport() 用于清除屏幕上的视口。 输入矩形采用屏幕坐标
    系统。
  • IGRAPHICS_Update() 可以使用最新的绘制操作更新屏幕。


IGraphics 接口的使用

使用 IGraphics 接口函数
1. 调用 ISHELL_CreateInstance() 以创建 IGraphics 接口实例。
2. 调用 IGRAPHICS_SetViewport() 指定屏幕上要显示的矩形区域。
3. 调用 IGRAPHICS_SetBackground() 设置背景颜色。
4. 调用 IGRAPHICS_ClearViewport()，通过填充背景颜色来清除视口。
5. 调用 IGRAPHICS_Translate() 或 IGRAPHICS_Pan() 在世界坐标系统中指定视图窗口。
6. 调用参数设置函数，设置绘制几何图元时所用的前景颜色、剪切区域、填充颜色和模式、着色模式和点大小。
7. 调用一个绘制函数，在屏幕上绘制 IGraphics 对象。 所有对象均采用世界坐标
系统。
8. 对所需的多个几何图元重复步骤 6 和 7。
9. 调用 IGRAPHICS_Update()，在屏幕上显示绘制的图形。
10. 调用 IGRAPHICS_Release()，释放 IGraphics 接口对象。

要包含的头文件列表

需要以下头文件：

AEEGraphics.h

函数列表

此接口的函数包括：

IGRAPHICS_AddRef()

IGRAPHICS_ClearRect()

IGRAPHICS_ClearViewport()

IGRAPHICS_DrawArc()

IGRAPHICS_DrawCircle()

IGRAPHICS_DrawEllipse()

IGRAPHICS_DrawEllipticalArc()

IGRAPHICS_DrawLine()

IGRAPHICS_DrawPie()

IGRAPHICS_DrawPoint()

IGRAPHICS_DrawPolygon()

IGRAPHICS_DrawPolyline()

IGRAPHICS_DrawRect()

IGRAPHICS_DrawRoundRectangle()

IGRAPHICS_DrawTriangle()

IGRAPHICS_EnableDoubleBuffer()

IGRAPHICS_GetAlgorithmHint()

IGRAPHICS_GetBackground()

IGRAPHICS_GetClip()

IGRAPHICS_GetColor()

IGRAPHICS_GetColorDepth()

IGRAPHICS_GetDestination()

IGRAPHICS_GetFillColor()

IGRAPHICS_GetFillMode()

IGRAPHICS_GetPaintMode()

IGRAPHICS_GetPointSize()

IGRAPHICS_GetStrokeStyle()

IGRAPHICS_GetViewport()

IGRAPHICS_Pan()

IGRAPHICS_Release()

IGRAPHICS_SetAlgorithmHint()

IGRAPHICS_SetBackground()

IGRAPHICS_SetClip()

IGRAPHICS_SetColor()

IGRAPHICS_SetDestination()

IGRAPHICS_SetFillColor()

IGRAPHICS_SetFillMode()

IGRAPHICS_SetPaintMode()

IGRAPHICS_SetPointSize()

IGRAPHICS_SetStokeStyle()

IGRAPHICS_SetViewport()

IGRAPHICS_StretchBlt()

IGRAPHICS_Translate()

IGRAPHICS_Update()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IGRAPHICS_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.IGRAPHICS_Release()

返回函数列表

IGRAPHICS_ClearRect()

说明：

此函数可通过填充背景颜色来清除屏幕矩形区域。 输入的矩形采用世界坐标系统。

原型：

int IGRAPHICS_ClearRect(IGraphics * pIGraphics, AEERect * pRect)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pRect | 指向指定要清除区域的矩形的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pRect 参数无效，则返回 EBADPARM。

备注：

调用本函数或 IGRAPHICS_ClearViewport() 函数之后，IGRAPHICS_SetBackground() 才会生效。

另请参阅：

AEERect

返回函数列表

IGRAPHICS_ClearViewport()

说明：

此函数可以将当前视口清除为背景颜色。

原型：

void IGRAPHICS_ClearViewport(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IGRAPHICS_DrawArc()

说明：

此函数用于绘制圆弧。 圆心、半径、起角和终角由 pArc 指定。 圆弧的颜色为当前的前景颜色。

原型：

int IGRAPHICS_DrawArc(IGraphics * pIGraphics, AEEArc * pArc)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pArc | 指向要绘制圆弧的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pArc 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEEArc

返回函数列表

IGRAPHICS_DrawCircle()

说明：

此函数用于绘制圆。 圆心和半径由 pCircle 指定。 圆周的颜色为当前的前景颜色。 如果启用填充模式，圆周内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawCircle(IGraphics * pIGraphics, AEECircle * pCircle)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pCircle | 指向要绘制圆的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pCircle 参数无效，则返回 EBADPARM。

备注：

输入的圆采用世界坐标系统。

另请参阅：

AEECircle

返回函数列表

IGRAPHICS_DrawEllipse()

说明：

此函数用于绘制由 pEllipse 指定的椭圆。 边框颜色为当前的前景颜色。 如果启用填充模式，椭圆内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawEllipse
(
IGraphics * pIGraphics,
AEEEllipse * pEllipse
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pEllipse | 指向要绘制椭圆的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pEllipse 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEEEllipse

返回函数列表

IGRAPHICS_DrawEllipticalArc()

说明：

此函数用于绘制椭圆弧。 边框颜色为当前的前景颜色。 如果启用填充模式，弧内将填满当前的填充颜色。 起角始于 x 轴正半轴，并沿逆时针方向旋转。

原型：

int IGRAPHICS_DrawEllipticalArc
(
IGraphics *pIGraphics,
AEERect *pRect,
int16 startAngle,
int16 arcAngle
)

参数：

pIGraphics | [in] | 指向 IGRAPHICS 接口对象的指针。
pRect | [in] | 指向包含此椭圆的矩形的指针
startAngle | [in] | 弧的起角以度为单位，0 度为 x 轴正方向，并沿逆时针方向增大。
arcAngle | [in] | 以度数表示的弧大小

返回值：

指示操作状态的错误代码

如果参数之一无效，则返回 EBADPARAM，

否则，返回 SUCCESS

备注：

无

另请参阅：

无

返回函数列表

IGRAPHICS_DrawLine()

说明：

此函数用于在给定起点和终点间绘制线段。 线段的颜色为当前的前景颜色。

原型：

int IGRAPHICS_DrawLine(IGraphics * pIGraphics, AEELine * pLine)

参数：

pGraphics | 指向 IGraphics 接口对象的指针。
pLine | 指向要绘制线段的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pLine 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEELine

返回函数列表

IGRAPHICS_DrawPie()

说明：

此函数用于绘制由 pPie 指定的饼图。 边框颜色为当前的前景颜色。 如果启用填充模式，则饼图内部将填满当前的填充颜色。

注意：BREW 的当前版本不支持填充模式。

原型：

int IGRAPHICS_DrawPie(IGraphics * pIGraphics, AEEPie * pPie)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pPie | 指向要绘制饼图的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pPie 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEEPie

返回函数列表

IGRAPHICS_DrawPoint()

说明：

此函数可以采用当前的点大小和前景颜色来绘制点。

原型：

int IGRAPHICS_DrawPoint(IGraphics * pIGraphics, AEEPoint * pPoint)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pPoint | 指向要绘制点的指针。

返回值：

如果成功绘制点，则返回 SUCCESS。

如果 pPoint 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEEPoint

返回函数列表

IGRAPHICS_DrawPolygon()

说明：

此函数用于绘制由 pPolygon 指定的多边形。 边框颜色为当前的前景颜色。 如果启用填充模式，其内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawPolygon
(
IGraphics * pIGraphics,
AEEPolygon * pPolygon
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pPolygon | 指向要绘制多边形的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pPolygon 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

该绘制操作有两种实现。 应用程序可通过调用 IGRAPHICS_SetAlgorithmHint() 来选择实现方式。 默认设置为 ALGORITHM_FAST。 ALGORITHM_ACCURATE 保证准确显示所有输入多边形的每个像素，但执行速度较慢。 ALGORITHM_FAST 执行速度较快，并对大多数多边形准确有效。

即使已选择 ALGORITHM_ACCURATE，如果符合以下条件之一，IGraphics 接口将自动选择快速实现：

  • 已设置 AEE_RO_COPY。
  • IGRAPHICS_SetColor() 设置的边框颜色和 IGRAPHICS_SetFillColor() 设置的填充颜色相同。
  • 换言之，只有符合以下所有条件时，才能选择“准确而缓慢”的实现。
  • 已选定 ALGORITHM_ACCURATE。
  • 边框颜色与填充颜色不同。
  • AEERasterOp 为 XOR。

另请参阅：

AEEPolygon

返回函数列表

IGRAPHICS_DrawPolyline()

说明：

此函数用于绘制由 pPolyline 指定的折线。 边框颜色为当前的前景颜色。

原型：

int IGRAPHICS_DrawPolyline
(
IGraphics * pIGraphics,
AEEPolyline * pPolyline
)

参数

:

pIGraphics | 指向 IGraphics 接口对象的指针。
pPolyline | 指向要绘制折线的指针

返回值：

如果函数成功绘制折线，则返回 SUCCESS。

如果 pPolyline 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEEPolyline

返回函数列表

IGRAPHICS_DrawRect()

说明：

此函数用于绘制由 pRect 指定的与坐标轴平行的矩形。 边框颜色为当前的前景颜色。 如果启用填充模式，矩形内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawRect(IGraphics * pIGraphics, AEERect * pRect)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pRect | 指向要绘制矩形的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pRect 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEERect

返回函数列表

IGRAPHICS_DrawRoundRectangle()

说明：

此函数用于绘制圆角矩形。 边框颜色为当前的前景颜色。 如果启用填充模式，矩形内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawRoundRectangle
(
IGraphics *pIGraphics,
AEERect *pRect,
int16 arcWidth,
int16 arcHeight
)

参数：

pIGraphics | [in] | 指向 IGRAPHICS 接口对象的指针。
pRect | [in] | 指向要绘制矩形的指针
arcWidth | [in] | 用于圆角弧的椭圆宽度
arcHeight | [in] | 用于圆角弧的椭圆高度

返回值：

指示操作状态的错误代码

如果参数之一无效，则返回 EBADPARAM，

否则，返回 SUCCESS

备注：

无。

返回值：

已增加的对象引用计数。

备注：

有效对象返回的引用计数为正值。

另请参阅：

无

返回函数列表

IGRAPHICS_DrawTriangle()

说明：

此函数用于绘制由 pTriangle 指定的三角形。 边框颜色为当前的前景颜色。 如果启用填充模式，其内部将填满当前的填充颜色。

原型：

int IGRAPHICS_DrawTriangle
(
IGraphics * pIGraphics,
AEETriangle * pTriangle
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pTriangle | 指向要绘制三角形的指针。

返回值：

如果成功，则返回 SUCCESS。

如果 pTriangle 参数无效，则返回 EBADPARM。

备注：

输入采用世界坐标系统。

另请参阅：

AEETriangle

返回函数列表

IGRAPHICS_EnableDoubleBuffer()

说明：

此函数可通过传递 TRUE 或 FALSE 来启用或禁用双缓冲。

注意：在 BREW 的当前版本中，BREW Emulator 不支持此函数，因此，返回值始终为 FALSE。

原型：

boolean IGRAPHICS_EnableDoubleBuffer
(
IGraphics * pIGraphics,
boolean flag
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
flag | 布尔值： 标记设为 TRUE 时可启用双缓冲。 标记设为 FALSE 时可禁用双缓冲。

返回值：

如果处理成功，则返回 SUCCESS。

否则，返回 FALSE。

注意：函数 IGRAPHICS_EnableDoubleBuffer(p, TRUE) 将始终返回 TRUE，因为只要有内存，双缓冲区就始终可用。

由于同样的原因，IGRAPHICS_EnableDoubleBuffer(p, FALSE) 将始终返回 FALSE。 因此该函数已基本没有用处。 但是为了保证二进制和源的向后兼容性，必须保留该
函数。

备注：

双缓冲使您可以维护两个单独的缓冲区。 在一个缓冲区上进行绘制的同时，可在另一个缓冲区上显示绘制的内容。 调用 IGRAPHICS_Update() 可以交换缓冲区。

另请参阅：

无

返回函数列表

IGRAPHICS_GetAlgorithmHint()

说明：

此函数用于查询当前的算法提示。 算法提示用于告知 IGraphics 实现是以快速方式还是以精确方式进行绘制（如果两种方式均可适用）。 （请参阅 AEEAlgorithmHint。） 在有些情况下，绘制非常精确的多边形需要耗费很多时间，因此向开发者提供此方式，以指定精度优先还是速度优先。

原型：

AEEAlgorithmHint IGRAPHICS_GetAlgorithmHint(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

当前的算法提示。

备注：

无

另请参阅：

AEEAlgorithmHint

IGRAPHICS_SetAlgorithmHint()

IGRAPHICS_DrawPolygon()

返回函数列表

IGRAPHICS_GetBackground()

说明：

此函数可以查询当前背景颜色的 RGB 值。

原型：

void IGRAPHICS_GetBackground
(
IGraphics * pIGraphics,
uint8 * r,
uint8 * g,
uint8 * b
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
r | 指向 RGB 红色成份的指针。
g | 指向 RGB 绿色成份的指针。
b | 指向 RGB 蓝色成份的指针。

返回值：

无

备注：

默认背景颜色为白色。

另请参阅：

无

返回函数列表

IGRAPHICS_GetClip()

说明：

此函数用于获取当前通过封闭几何图元指定的剪切区域。

原型：

boolean IGRAPHICS_GetClip(IGraphics * pIGraphics, AEEClip * pShape)

参数：

pIGraphics 填充颜色 | 指向 IGraphics 接口对象的指针。
pShape | 指向当前剪切形状的指针。

返回值：

如果查询成功，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

AEEClip

返回函数列表

IGRAPHICS_GetColor()

说明：

此函数用于获取当前前景颜色的 RGBA 值。

原型：

void IGRAPHICS_GetColor
(
IGraphics * pIGraphics,
uint8 * r,
uint8 * g,
uint8 * b,
uint8 * alpha
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
r | 指向 RGBA 值红色成份的指针
g | 指向 RGBA 值绿色成份的指针。
b | 指向 RGBA 值蓝色成份的指针。
alpha | Alpha 值。

返回值：

无

备注：

alpha 参数在当前版本中只是占位符， 对前景颜色没有影响。

另请参阅：

无

返回函数列表

IGRAPHICS_GetColorDepth()

说明：

此函数用于获取设备的颜色深度。

原型：

uint8 IGRAPHICS_GetColorDepth(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

颜色深度。

备注：

无

另请参阅：

ISHELL_GetDeviceInfo()

返回函数列表

IGRAPHICS_GetDestination()

说明：

此函数用于获取 IGRAPHICS 函数将要渲染的目标位图。

原型：

IBitmap* IGRAPHICS_GetDestination(IGraphics *pIGraphics)

参数：

pIGraphics
指向 IGRAPHICS 接口对象的指针。

返回值：

指向当前目标位图的指针。

备注：

如果此函数返回 NULL，则表明出现错误。

另请参阅：

IGRAPHICS_SetDestination()

返回函数列表

IGRAPHICS_GetFillColor()

说明：

此函数用于获取当前填充颜色的 RGBA 值。

原型：

void IGRAPHICS_GetFillColor
(
IGraphics * pIGraphics,
uint8 * pRed,
uint8 * pGreen,
uint8 * pBlue,
uint8 * pAlpha
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pRed | RGBA 值的红色成份。
pGreen | RGBA 值的绿色成份。
pBlue | RGBA 值的蓝色成份。
pAlpha | Alpha 值。

返回值：

无

备注：

pAlpha 参数在当前版本中只是占位符， *pAlpha 值对填充颜色没有影响。

另请参阅：

无

返回函数列表

IGRAPHICS_GetFillMode()

说明：

该函数用于查询当前的填充模式。

原型：

boolean IGRAPHICS_GetFillMode(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

如果为填充，则返回 TRUE。

如果为未填充，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IGRAPHICS_GetPaintMode()

说明：

此函数用于获取当前的着色模式。

原型：

AEEPaintMode IGRAPHICS_GetPaintMode(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

当前着色模式的枚举值。

备注：

无

另请参阅：

AEEPaintMode

返回函数列表

IGRAPHICS_GetPointSize()

说明：

此函数用于获取以像素数目表示的当前点的大小。

原型：

uint8 IGRAPHICS_GetPointSize(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

当前点大小。

备注：

无

另请参阅：

无

返回函数列表

IGRAPHICS_GetStrokeStyle()

说明：

此函数用于获取 IGRAPHICS 绘图函数将使用的描边样式。

原型：

AEEStrokeStyle IGRAPHICS_GetStrokeStyle(IGraphics *pIGraphics)

参数：

pIGraphics
指向 IGRAPHICS 接口对象的指针。

返回值：

返回当前的描边样式。

备注：

无。

另请参阅：

IGRAPHICS_SetStokeStyle()

返回函数列表

IGRAPHICS_GetViewport()

说明

此函数用于获取当前的绘制视口（屏幕坐标框中的矩形区域）。

原型：

boolean IGRAPHICS_GetViewport
(
IGraphics * pIGraphics,
AEERect * pRect,
boolean * framed
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pRect | 指向指定当前视口区域矩形的指针
framed | 如果视口有边框，则为 TRUE，否则为 FALSE。

返回值：

如果成功，则返回 TRUE。

否则，返回 FALSE。

备注：

输出采用屏幕坐标系统。

另请参阅：

IGRAPHICS_SetViewport()
AEERect

返回函数列表

IGRAPHICS_Pan()

说明：

此函数用于在世界坐标系统中重置窗口中心。 坐标对 (cx、cy) 就是放置照相机的世界坐标。

原型：

void IGRAPHICS_Pan(IGraphics * pIGraphics, int16 cx, int16 cy)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
cx | 世界坐标框新中心的 X 坐标。
cy | 世界坐标框新中心的 Y 坐标。

返回值：

无

备注：

无

副作用

无

另请参阅：

IGRAPHICS_Translate()

返回函数列表

IGRAPHICS_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IGRAPHICS_AddRef()

返回函数列表

IGRAPHICS_SetAlgorithmHint()

说明：

此函数用于设置一些绘制操作的算法提示。 算法提示用于告知 IGraphics 实现是以快速方式还是以精确方式进行绘制（如果两种方式均可适用）。 （请参阅 AEEAlgorithmHint。） 在有些情况下，绘制非常精确的多边形需要耗费很多时间，
因此向开发者提供此方式，以指定精度优先还是速度优先。

原型：

void IGRAPHICS_SetAlgorithmHint
(
IGraphics * pIGraphics,
AEEAlgorithmHint hint
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
hint | 算法提示。

返回值：

无

备注：

算法提示仅对 IGRAPHICS_DrawPolygon 有效。 默认情况下，算法提示设置为 ALGORITHM_FAST。

副作用：

算法提示设置为输入参数 hint。

另请参阅：

AEEAlgorithmHint

IGRAPHICS_DrawPolygon()

IGRAPHICS_GetAlgorithmHint()

返回函数列表

IGRAPHICS_SetBackground()

说明：

此函数用于设置当前背景颜色的 RGB 值。 除非设置为其它值，否则该颜色将一直有效。

原型：

RGBVAL IGRAPHICS_SetBackground
(
IGraphics * pIGraphics,
uint8 r,
uint8 g,
uint8 b
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
r | RGB 值的红色成份。
g | RGB 值的绿色成份。
b | RGB 值的蓝色成份。

返回值：

已更新的当前背景颜色 RGB 值。

备注：

在调用 IGRAPHICS_ClearRect() 或 IGRAPHICS_ClearViewport() 之前，程序不显示新的背景颜色。

每种颜色成分（红、绿和蓝）的值必须是 0（零）到 255 之间的正值。此范围之外的任何整数值都将被转换为 0（零）到 255 之间的值，但是，转换本身取决于机器。
建议开发者使用范围内的值，以使颜色达到预期效果。

另请参阅：

RGBVAL

IGRAPHICS_GetBackground()

返回函数列表

IGRAPHICS_SetClip()

说明：

此函数用于设置剪切区域。 只有位于剪切区域内的图形内容才显示在屏幕上。 如果指针 pShape 为 NULL，剪切区域将重置为显示窗口。 剪切采用世界坐标系统。

注意：当前版本的 BREW 仅支持矩形、圆和椭圆等剪切形状。 如果传递其它剪切形状，则此函数将返回 FALSE，且前一个剪切形状继续有效（将来版本将支持其它剪切形状）。

原型：

boolean IGRAPHICS_SetClip
(
IGraphics * pIGraphics,
AEEClip * pShape,
uint8 nFlag
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
pShape | 指向剪切形状的指针。
pFlag | 位图标记。

返回值：

如果成功设置剪切区域，则返回 TRUE。

否则，返回 FALSE。

备注：

如果将 nFlag 设置为 AEE_GRAPHICS_FRAME，则会在设置剪切区域的同时，
用当前的前景颜色和着色模式绘制外框。

如果将 nFlag 设置为 AEE_GRAPHICS_CLEAR，则会在设置剪切区域的同时，
清除其内部。

如果将 nFlag 设置为 AEE_GRAPHICS_FILL，则会在设置剪切区域的同时，用当前填充颜色和着色模式填充其内部。

另请参阅：

AEEClip

返回函数列表

IGRAPHICS_SetColor()

说明：

此函数用于设置当前的 RGBA 值。 在重新调用此函数设置其它 RGBA 值之前，所有后续的图形对象均采用此颜色绘制。

原型：

RGBVAL IGRAPHICS_SetColor
(
IGraphics * pIGraphics,
uint8 r,
uint8 g,
uint8 b,
uint8 alpha
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
r | RGBA 值的红色成份。
g | RGBA 值的绿色成份。
b | RGBA 值的蓝色成份。
alpha | Alpha 值。

返回值：

已更新的前景颜色 RGBA 值。

备注：

当前版本中，alpha 值只是占位符，对前景颜色没有影响。 最终，该值将用于支持透明色和颜色混合。 默认前景颜色为黑色。

另请参阅：

RGBVAL

IGRAPHICS_GetColor()

返回函数列表

IGRAPHICS_SetDestination()

说明：

此函数用于设置 IGRAPHICS 函数要渲染的目标位图。

原型：

int IGRAPHICS_SetDestination(IGraphics *pIGraphics, IBitmap *pDst)

参数：

pIGraphics | 指向 IGRAPHICS 接口对象的指针。
pDst | 用于渲染的 IBitmap 接口指针，如果为 NULL 则设为屏幕位图。

返回值：

如果成功设置目标位图，则返回 SUCCESS。

如果设置目标位图失败，则返回 EFAILED。

备注：

实例化 IGraphics 后，默认位图为屏幕位图。

使用值为 NULL 的 pDst 调用此函数，可将目标位图恢复为默认设置。

另请参阅：

IGRAPHICS_GetDestination()

返回函数列表

IGRAPHICS_SetFillColor()

说明：

此函数用于设置后面所有封闭几何图元的填充颜色。

原型：

RGBVAL IGRAPHICS_SetFillColor
(
IGraphics * pIGraphics,
uint8 r,
uint8 g,
uint8 b,
uint8 alpha
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
r | RGBA 值的红色成份。
g | RGBA 值的绿色成份。
b | RGBA 值的蓝色成份。
alpha | Alpha 值。

返回值：

已更新的当前填充色 RGBA 值。

备注：

无

另请参阅：

RGBVAL

返回函数列表

IGRAPHICS_SetFillMode()

说明：

此函数可以通过传递 TRUE，为后续所有封闭的几何图元启用填充模式， 通过传递 FALSE，禁用填充模式。

原型：

boolean IGRAPHICS_SetFillMode(IGraphics * pIGraphics, boolean fFill)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
fFill | 布尔值： 将 fFill 设置为 TRUE 可启用填充模式。 将 fFill 设置为 FALSE 可禁用填充模式。

返回值：

如果已启用当前填充模式，则返回 TRUE。

如果未启用当前填充模式，则返回 FALSE。

备注：

如果作为输入参数传递的是无效值（不是 TRUE 或 FALSE），则默认情况下，填充模式将设置为 FALSE。

另请参阅：

无

返回函数列表

IGRAPHICS_SetPaintMode()

说明：

此函数用于设置着色模式。 在 AEE_PAINT_COPY 模式下，新的图形内容将覆盖原有内容。 在 AEE_PAINT_XOR 模式下，颜色取决于新旧颜色的二进制异或操作。

假定任意一种背景颜色和一种新的前景颜色，将前景颜色与背景颜色进行两次异或，便会恢复背景颜色。

原型：

AEEPaintMode IGRAPHICS_SetPaintMode
(
IGraphics * pIGraphics,
AEEPaintMode mode
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
mode | 着色模式的枚举值。

返回值：

已更新的着色模式枚举值。

备注：

如果作为输入模式参数传递的是无效整数（枚举）值，则默认情况下，着色模式为 AEE_PAINT_COPY。

另请参阅：

AEEPaintMode

返回函数列表

IGRAPHICS_SetPointSize()

说明：

此函数用于设置以像素数表示的点大小（宽度）。

原型：

uint8 IGRAPHICS_SetPointSize(IGraphics * pIGraphics, uint8 u8Size)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
u8Size | 以像素数目表示的点大小（宽度）。

返回值：

点大小的更新值。

备注：

无

另请参阅：

无

返回函数列表

IGRAPHICS_SetStokeStyle()

说明：

此函数用于设置 IGRAPHICS 绘图函数将使用的描边样式。

原型：

AEEStrokeStyle IGRAPHICS_SetStokeStyle
(
IGraphics *pIGraphics,
AEEStrokeStyle strokeStyle
)

参数：

pIGraphics | 指向 IGRAPHICS 接口对象的指针。
strokeStyle | 用于绘制的描边样式。

返回值：

返回前一个描边样式。

备注：

实例化 IGraphics 后，默认的描边样式为 STROKE_SOLID。

另请参阅：

IGRAPHICS_GetStrokeStyle()

返回函数列表

IGRAPHICS_SetViewport()

说明：

用于显示的世界坐标区域称为窗口。 显示设备上窗口映射至的区域称为视口。

此函数用于设置绘制视口矩形区域。 默认视口为无边框的屏幕。 如果 pRect 为 NULL，此函数将把视口重置为默认视口，并将剪切区域重置为默认视口。

原型：

boolean IGRAPHICS_SetViewport
(
IGraphics * pIGraphics,
AEERect * pRect,
uint8 nFlag
)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。
pRect
指向用于指定显示区域的矩形形状的指针。
nFlag
不同选项的位图标记：
  • 如果将标记设置为 AEE_GRAPHICS_FRAME，则 dx、dy 的最小值为 3 像素。
  • 如果将标记设置为 AEE_GRAPHICS_NONE，则 dx、dy 的最小值为 1 像素。
  • 如果 IGRAPHICS_SetViewport 出于任何原因返回 FALSE，则保留先前的视口设置。

返回值：

如果成功，将返回 TRUE。

否则，返回 FALSE。

备注：

只有显示区域非空，并且视口完全包含在实际屏幕中，此函数才会返回 TRUE。
否则，将返回 FALSE。

如果设置了 AEE_GRAPHICS_FRAME，将绘出外框。

如果设置了 AEE_GRAPHICS_CLEAR，则会将视口清除为背景颜色。

其它 IGraphics 函数的输入采用世界坐标系统，但是此函数的输入采用屏幕坐标系统。

另请参阅：

AEERect
IGRAPHICS_GetViewport()
返回函数列表

IGRAPHICS_StretchBlt()

说明：

此函数可以将输入位图移到指定位置并指定宽度/高度。

原型：

void IGRAPHICS_StretchBlt
(
IGraphics * pIGraphics,
int16 destX,
int16 destY,
int16 destW,
int16 destH,
const void * pbmSource,
AEERasterOp dwRopCode
)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
destX | 指定目标矩形区域左上角的 x 坐标。
destY | 指定目标矩形区域左上角的 y 坐标。
destW | 目标宽度。
destH | 目标高度。
pbmSource | 指向包含源位图的 Windows BMP 结构的指针。 所指向的数据不包括 AEE 头文件。 数据应从 BITMAPFILEHEADER 开始。 BMP 应未 压缩。
dwRopCode | 指定在执行位块传输时必须使用的光栅操作。

返回值：

无

备注：

无

另请参阅：

AEERasterOp

返回函数列表

IGRAPHICS_Translate()

说明：

此函数可以在世界坐标系统中平移窗口的原点， 这样可以显示不同的世界坐标区域。 单位是像素数目。 窗口的原点总在其左上角，这是世界坐标系统的默认原点。 平移的结果是，所有几何图元均平移相同的距离，但平移的方向与视口中的方向相反。
有关窗口和视口的定义，请参阅 IGRAPHICS_SetViewport()。

原型：

void IGRAPHICS_Translate(IGraphics * pIGraphics, int16 x, int16 y)

参数：

pIGraphics | 指向 IGraphics 接口对象的指针。
x | 窗口原点沿 X 轴平移 x 像素。
y | 窗口原点沿 Y 轴平移 y 像素。

返回值：

无

备注：

将窗口想象成照相机有助于概念上的理解。 平移照相机可使其指向不同的世界坐标区域。 世界坐标系统是开发者设计的场景。

注意： 只有在调用 IGRAPHICS_Translate() 函数“之后”，绘制的对象才会平移。

另请参阅：

IGRAPHICS_Pan()

返回函数列表

IGRAPHICS_Update()

说明：

此函数用于指示已在设备位图上执行绘制操作，并且应将这些更改传至显示硬件。 IDisplay、IGraphics 和 IBitmap 方法在设备位图上的绘制并不会直接反映到显示硬件。 只有更新物理显示时，用户才能够看见结果。 此函数可排列实际的更新操作，因此能够重复调用而不会对性能产生不良影响。 实际显示将在应用程序向 BREW 发出程序控制后进行异步更新。

原型：

void IGRAPHICS_Update(IGraphics * pIGraphics)

参数：

pIGraphics
指向 IGraphics 接口对象的指针。

返回值：

无

备注：

此版本不支持双缓冲。

另请参阅：

无

返回函数列表


IHash 接口

IHash 接口函数用于散列数据。 当前仅支持 MD5 算法。 要使用 IHash 接口中的函数，请调用 ISHELL_CreateInstance() 函数创建 IHash（SHA1,MD2） 接口实例。

在使用 IHash 接口指针调用函数之后，如果已完成对 IHash 接口的访问，则在该接口中调用 IHASH_Release()。

要包含的头文件列表

需要以下头文件：

AEESecurity.h

函数列表

此接口的函数包括：

IHASH_AddRef()

IHASH_GetResult()

IHASH_Release()

IHASH_Restart()

IHASH_Update()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IHASH_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.IHASH_Release()

返回函数列表

IHASH_GetResult()

说明：

在完成对 IHASH_Update() 的所有调用之后，应调用该函数以获取散列结果。

原型：

int IHASH_GetResult(IHash* pIHash, byte* pbData, int* pcbData)

参数：

pIHash | [in] | 指向 IHash 接口对象的指针
pbData | [out] | 指向获取散列结果的数据的指针
pcbData | [in/out] | 指向缓冲区 pbData 大小的指针。 返回时，该指针包含散列结果的大小。

返回值：

如果成功，则返回 SUCCESS。

如果缓冲区不足以容纳散列结果，则返回 AEE_HASH_MORE_DATA。

备注：

无

另请参阅：

无

返回函数列表

IHASH_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IHASH_AddRef()

返回函数列表

IHASH_Restart()

说明：

此函数用于重新启动散列过程。 在需要散列新的数据流时，必须调用此函数。

原型：

void IHASH_Restart(IHash* pIHash)

参数：

pIHash
指向 IHash 接口对象的指针。

返回值：

void

备注：

无

另请参阅：

无

返回函数列表

IHASH_Update()

说明：

此函数用于向散列对象馈送数据。 在散列长数据流或不连续的数据流时，可以多次调用此函数。

原型：

void IHASH_Update(IHash* pIHash, byte* pbData, int cbData)

参数：

pIHash | 指向 IHash 接口对象的指针。
pbData | 指向要散列数据的指针。
cbData | 要散列数据（存储在 pbData 中）的长度。

返回值：

void

备注：

无

另请参阅：

无

返回函数列表


IHashCTX 接口

IHashCTX 接口函数用于散列数据， 当前支持 MD5、MD2 和 SHA1 算法。 要使用 IHash 接口中的函数，请调用 ISHELL_CreateInstance() 创建 IHash 接口实例，并维护适当的散列上下文数据结构。 除了 IHashCTX 对象不包含上下文之外，IHashCTX 接口与 IHash 接口非常相似。

要包含的头文件列表

需要以下头文件：

AEESecurity.h

函数列表

该接口的函数包括：

IHASHCTX_AddRef()

IHASHCTX_Final()

IHASHCTX_Init()

IHASHCTX_QueryInterface()

IHASHCTX_Release()

IHASHCTX_Update()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IHASHCTX_AddRef()

说明：

此函数用于递增 IHashCTX 接口对象的引用计数， 以便多个调用者共享该对象。
引用计数为 0（零）时将释放该对象。

原型：

uint32 IHASHCTX_AddRef(IHash * pIHashCTX)

参数：

pIHashCTX
指向 IHashCTX 接口对象的指针。

返回值：

已递增的对象引用计数。

备注：

有效对象返回正的引用计数。

另请参阅：

IHASHCTX_Release()

返回函数列表

IHASHCTX_Final()

说明：

此函数用于在完成所有 IHASHCTX_Update() 调用后，获取散列结果。

原型：

int IHASHCTX_Final(
IHashCTX* pIHashCTX,
void *pCTX,
int nCTXSize,
byte* pbData,
int* pcbData);

参数：

pIHashCTX | [in] | 指向 IHashCTX 接口对象的指针
pCTX | [in] | 指向散列上下文结构的指针
nCTXSize | [in] | 散列上下文结构的大小
pbData | [out] | 指向获取散列结果的数据的指针
pcbData | [in/out] | 指向缓冲区 pbData 大小的指针。 返回时，该指针包含散列结果的大小。

返回值：

SUCCESS

AEE_HASH_MORE_DATA： 缓冲区大小不足以容纳散列结果。

备注：

无

另请参阅：

无

返回函数列表

IHASHCTX_Init()

说明：

在散列之前或需要重新启动散列过程时需要调用此函数。 在需要散列新的数据流时，也必须调用此函数。

原型：

void IHASHCTX_Init(IHashCTX* pIHashCTX, void *pCTX, int nCTXSize);

参数：

pIHashCTX | 指向 IHashCTX 接口对象的指针。
pCTX | 指向散列上下文结构的指针。
nCTXSize | 散列上下文结构的大小。

返回值：

void

备注：

无

另请参阅：

无

返回函数列表

IHASHCTX_QueryInterface()

说明：

此函数用于根据输入的类 ID，获取指向接口或数据的指针

原型：

static int IHashCTX_QueryInterface(
ISource *pIHashCTX,
AEECLSID id,
void **ppo);

参数：

pIHashCTX | 指向 IHashCTX 接口的指针。
id | 类 id。
ppo | 输出时，指向 RandomSource 对象的指针（如果可用）。

返回值：

SUCCESS

ECLASSNOTSUPPORT

备注：

无

另请参阅：

无

返回函数列表

IHASHCTX_Release()

说明：

此函数用于递减 IHashCTX 接口对象的引用计数。 引用计数为 0（零）时，将从内存中释放该对象且不再有效。

原型：

uint32 IHASHCTX_Release(IHash * pIHashCTX)

参数：

pIHashCTX
指向 IHashCTX 接口对象的指针。

返回值：

引用计数： 已递减的对象引用计数。

如果已经释放对象，且不再有效，则为 0（零）。

备注：

无

另请参阅：

IHASHCTX_AddRef()

返回函数列表

IHASHCTX_Update()

说明：

此函数用于向散列对象馈送数据。 在散列长数据流或不连续的数据流时，可以多次
调用此函数。

原型：

void IHASHCTX_Update(
IHashCTX* pIHashCTX,
void *pCTX,
int nCTXSize,
const void* pData,
int nDataLen);

参数：

pIHashCTX | [in] | 指向 IHashCTX 接口对象的指针。
pCTX | [in] | 指向散列上下文结构的指针。
nCTXSize | [in] | 散列上下文结构的大小。
pData | [in] | 指向要散列的数据的指针。
nDataLen | [in] | 要散列的数据的长度（保存在 pbData 中）。

返回值：

void

备注：

无

另请参阅：

无

返回函数列表


IHeap 接口

IHeap 接口中的函数可用于分配和释放内存，并可以获取有关可用和正在使用的设备内存量的信息。 对于简单的内存分配任务，可以使用 AEEStdLib.h 文件中定义的 MALLOC() 和 FREE() 宏指令。

IHEAP_CheckAvail() 用于检查是否存在足够的内存来分配指定大小的内存块。IHEAP_GetMemStats() 用于返回系统中当前正在使用的内存总量（字节数）。
使用 ISHELL_GetDeviceInfo() 可获取内存总量。

IHEAP_Malloc() 用于分配指定大小的内存块，并返回指向该内存块的指针。IHEAP_MallocRec() 使用数据类型作为输入，为此数据类型的单个实例分配足够内存，
并返回指向所分配内存的指针（指针转换为指定类型）。IHEAP_Realloc() 用于更改已分配内存块的大小。IHEAP_StrDup() 可以复制字符串，并返回指向已分配用来保存副本的内存的指针。IHEAP_Free() 用于释放这些函数分配的内存块。

要包含的头文件列表

需要以下头文件：

AEEHeap.h

函数列表

此接口的函数包括：

IHEAP_AddRef()

IHEAP_CheckAvail()

IHEAP_Free()

IHEAP_GetMemStats()

IHEAP_Malloc()

IHEAP_MallocRec()

IHEAP_Realloc()

IHEAP_Release()

IHEAP_StrDup()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IHEAP_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.IHEAP_Release()

返回函数列表

IHEAP_CheckAvail()

说明：

此函数用于检查是否可以分配指定大小的内存块。 该函数不会真正分配内存， 它返回 TRUE 或 FALSE，指明是否可以分配指定大小的内存块。

原型：

boolean IHEAP_CheckAvail(IHeap * pIHeap, uint32 dwSize)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
dwSize | 需验证其分配的内存块的大小。

返回值：

如果可以分配指定大小的内存块，则返回 TRUE。

如果失败或无法分配指定大小的内存块，则返回 FALSE。

备注：

无

副作用：

此函数可能会预排堆，并破坏所有相邻的空闲块。

另请参阅：

IHEAP_GetMemStats()

返回函数列表

IHEAP_Free()

说明：

此函数用于释放已分配的内存块， 它将内存释放回内存池。

原型：

void IHEAP_Free(IHeap * pIHeap, void * pMemFree)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
pMemFree | 指向要释放内存块的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IHEAP_GetMemStats()

说明：

此函数用于返回有关当前所用内存总量的统计信息。 要检查是否可以分配特定大小的内存块，必须调用函数 IHEAP_CheckAvail()。 要获取系统的总内存量，则必须调用函数 ISHELL_GetDeviceInfo()。

原型：

uint32 IHEAP_GetMemStats(IHeap * pIHeap)

参数：

pIHeap
指向 IHeap 接口对象的指针。

返回值：

系统中已使用的总内存量

备注：

无

另请参阅：

IHEAP_CheckAvail()

ISHELL_GetDeviceInfo()

返回函数列表

IHEAP_Malloc()

说明：

此函数用于分配所请求大小的内存块，并返回指向该内存块的指针。

原型：

void * IHEAP_Malloc(IHeap * pIHeap, uint32 dwSize)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
dwSize | 指定要分配内存块的大小。

返回值：

如果成功，则返回指向已分配内存块的指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

IHEAP_Realloc()

IHEAP_MallocRec()

返回函数列表

IHEAP_MallocRec()

说明：

此函数用于分配指定标准数据类型所需的内存。 在返回至调用程序之前，它会将分配的指针指向该数据类型。

原型：

(type *)IHEAP_MallocRec(IHeap * pIHeap, type dataType)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
dataType | 指定需为其分配内存的标准数据类型。

返回值：

如果成功，则返回指向所请求数据类型的指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

IHEAP_Malloc()

IHEAP_Realloc()

返回函数列表

IHEAP_Realloc()

说明：

此函数用于重新分配内存块并更改其大小。

原型：

void * IHEAP_Realloc
(
IHeap * pIHeap,
void * pMemBlock,
uint32 dwNewSize
)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
pMemBlock | 指向需要重新分配的内存块的指针。 如果pMemblock 为 NULL，则此函数的功能相当于 IHEAP_Malloc()，并分配 dwNewSize 字节的新内存块。
dwNewSize | 指定内存块的新容量。

返回值：

如果成功，则返回指向重新分配的块的指针。

如果失败，则返回 NULL。

备注：

如果大小为 0（零）但 pMemBlock 有效，或者没有足够的可用内存将 pMemBlock 扩展到指定大小，将返回 NULL。 第一种情况下，将释放原始块。 第二种情况下，
原始块不改变。

另请参阅：

无

返回函数列表

IHEAP_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IHEAP_AddRef()

返回函数列表

IHEAP_StrDup()

说明：

此函数用于复制指定的字符串。 它可以为新字符串分配内存，然后将输入字符串的内容复制到此新字符串中， 最后返回新字符串。

原型：

AECHAR * IHEAP_StrDup(IHeap * pIHeap, AECHAR * pszIn)

参数：

pIHeap | 指向 IHeap 接口对象的指针。
pszIn | 指向需复制字符串的指针。

返回值：

如果成功，则返回指向复制字符串的指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

无

返回函数列表


IHtmlViewer 接口

IHtmlViewer 接口允许应用程序控制 HTML 浏览器对象。 BREW 提供了支持 HTML 3.2 版子集的 HTML 浏览器。 浏览器不是应用程序，而是一个由主机应用程序调用的对象。 它可以处理 HTML 文档，在屏幕上显示其直观图像，并允许用户对文档执行操作：滚动、使用链接以及在表单字段中输入数据。

HTML 浏览器本身不能以任何方式访问网络。 如果用户跟从链接或提交表单，会产生发往主机应用程序的通知。

BREW 当前版本中的 HTML 浏览器使得开发者能够在一定程度上增加应用程序接口的灵活度，和简化应用程序开发。 设置功能时，重点考虑其是否能与应用程序灵活集成。 而它在 HTML 格式化和处理残缺内容方面的功能则比较有限。 应正确构造浏览器的 HTML，对非空元素使用起始和终止标记，并且不要错误匹配终止标记。 因此，建议采用通过特定应用程序测试过的 HTML，但这不表示可支持任意内容（从各种网站获取）。

支持的 HTML 主要功能包括：

  • 超文本链接
  • 简单的 HTML 表单支持：文本输入、列表、提交按钮、复选框和单选按钮
  • 内嵌图像或插件
  • 水平对齐： 左对齐、居中和右对齐
  • 粗体文本（用 AEE_FONT_BOLD 字体显示）
  • 大字体文本（用 AEE_FONT_LARGE 字体显示）
  • 文本颜色

BREW 当前版本不支持的 HTML 主要功能包括：

  • Java 小程序
  • FRAMESET
  • 脚本
  • 背景颜色
  • 级联样式表
  • Unicode 字符参考

HTML 浏览器可以使用 AEECLSID_HTML ClassID 创建。

要包含的头文件列表

需要以下头文件：

AEEHTMLViewer.h

函数列表

此接口的函数包括：

IHTMLVIEWER_AddRef()

IHTMLVIEWER_FindElem()

IHTMLVIEWER_GetAttrValue()

IHTMLVIEWER_GetElemText()

IHTMLVIEWER_GetError()

IHTMLVIEWER_GetOption()

IHTMLVIEWER_GetProperties()

IHTMLVIEWER_GetRect()

IHTMLVIEWER_GetViewState()

IHTMLVIEWER_HandleEvent()

IHTMLVIEWER_IsActive()

IHTMLVIEWER_IsBusy()

IHTMLVIEWER_LoadSource()

IHTMLVIEWER_LoadStream()

IHTMLVIEWER_ParseBuffer()

IHTMLVIEWER_Redraw()

IHTMLVIEWER_Release()

IHTMLVIEWER_Reset()

IHTMLVIEWER_SetActive()

IHTMLVIEWER_SetData()

IHTMLVIEWER_SetIndent()

IHTMLVIEWER_SetLinkColor()

IHTMLVIEWER_SetNotifyFn()

IHTMLVIEWER_SetOption()

IHTMLVIEWER_SetProperties()

IHTMLVIEWER_SetRect()

IHTMLVIEWER_SetSBWidth()

IHTMLVIEWER_SetTextColor()

IHTMLVIEWER_SetType()

IHTMLVIEWER_SetURL()

IHTMLVIEWER_SetViewState()

IHTMLVIEWER_SetVSpace()

IHTMLVIEWER_SetIWeb()

IHTMLVIEWER_Stop()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IHTMLVIEWER_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IHTMLVIEWER_Release()

返回函数列表

IHTMLVIEWER_FindElem()

说明：

此函数用于查找给定元素名及出现次数的元素。

原型：

int32 IHTMLVIEWER_FindElem
(
IHtmlViewer * pIHtmlViewer,
const char * pszElem,
int nIndex
)

参数：

pIHtmlViewer | 指向 IHtmlViewer 接口对象的指针。
pszElem | 要查找元素的名称，它是以零结束的 ASCII 字符串 （不区分大小写）
nIndexd | 出现次数（0 => 第一个元素，1 => 第二个元素，等等）。

返回值：

如果找到该元素，则返回该元素在文档中的位置所对应的非负数

如果未找到 pszElem，则返回 IHTMLVIEWER_NOTFOUND。

如果 pszElem 不是可识别的元素名，则返回 IHTMLVIEWER_BADELEMENT。 该函数只能检测可识别元素。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_GetAttrValue()

说明：

此函数用于获取元素的属性值。

原型：

int32 IHTMLVIEWER_GetAttrValue
(
IHtmlViewer * pIHTMLViewer,
int32 monopoles,
const char * pszAttr,
char * pchBuf,
int32 cbBuf
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nElemPos | 元素在文档中的位置
pszAttr | 属性名，它是以零结束的 ASCII 字符串（不区分大小写）
pchBuf | 指向保存结果（以零结束的字符串）的缓冲区开始位置的指针
cbBuf | 缓冲区大小（以字节为单位）

返回值：

如果未找到该属性，则返回 IHTMLVIEWER_NOTFOUND

如果 nElemPos 无效，则返回 IHTMLVIEWER_BADELEMENT。

如果 pszAttr 不是可识别属性名，则返回 IHTMLVIEWER_BADATTR。 该函数只能查询可识别的属性。

如果已指定属性，但未分配值，则返回 IHTMLVIEWER_NOVALUE。

非负数所对应长度的字符串将被复制到 pchBuf 中。

返回的值可能比 cbBuf 大，但这种情况下，缓冲区内将只写入 cbBuf 字节。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_GetElemText()

说明：

此函数用于获取元素的文本内容。 它将忽略包含的元素，并连接文本内容的分离部分（包括子元素的内容）。

原型：

int32 IHTMLVIEWER_GetElemText
(
IHtmlViewer * pIHTMLViewer,
int32 nElemPos,
char * pchBuf,
int32 cbBuf
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nElemPos | 文档中元素的位置。 它可以从 IHTMLVIEWER_FindElem() 中获得。
pchBuf | 指向保存结果（以零结束的字符串）的缓冲区开始位置的指针
cbBuf | 缓冲区大小（以字节为单位）

返回值：

如果失败，则返回 IHTMLVIEWER_BADELEMENT。 仅当 nElemPos 值无效时才会出现这种情况。

如果成功，则返回结果字符串的长度。

如果为空元素或不包含文本的元素，则返回 0（零）。

返回的值可能比 cbBuf 大，但这种情况下，缓冲区内将仅写入 cbBuf 字节。

另请参阅：

IHTMLVIEWER_FindElem()

IHTMLVIEWER_GetAttrValue()

返回函数列表

IHTMLVIEWER_GetError()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_N_ERROR) 的简写函数。

原型：

int IHTMLVIEWER_GetError(IHtmlViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

返回 IHtmlViewer 特定的错误代码。

备注：

此函数实际上是一个调用 IHTMLVIEWER_GetOption() 的宏。

另请参阅：

IHTMLVIEWER_GetOption()

返回函数列表

IHTMLVIEWER_GetOption()

说明：

此函数用于获取说明浏览器状态的多个值中的一个。 请注意，此函数不能获取通过 IHTMLVIEWER_SetOption() 设置的值。

原型：

int IHTMLVIEWER_GetOption
(
IHtmlViewer * pIHTMLViewer,
int32 nID,
HVOpt * ppVal
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nID | 所获取值的 ID。
ppVal | 变量地址或保存结果的内存位置。

返回值：

如果已获取选项，则返回 SUCCESS；* ppVal 将保存结果。

如果不支持选项 ID，则返回 EUNSUPPORTED；* ppVal 将保持不变。

备注：

调用程序不能直接调用此函数；每个单独的选项都定义有宏
（请参阅 IHTMLVIEWER_SetOption()）。

另请参阅：

IHTMLVIEWER_SetOption()

IHTMLVIEWER_GetError()

返回函数列表

IHTMLVIEWER_GetProperties()

说明：

此函数用于返回特定于控件的属性或标记。

原型：

uint32 IHTMLVIEWER_GetProperties(IHTMLViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

32 位的控件属性。

备注：

无

另请参阅：

IHTMLVIEWER_SetProperties()

返回函数列表

IHTMLVIEWER_GetRect()

说明：

此函数可以为输入 AEERect 结构的指针填入控件的活动屏幕坐标。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

原型：

void IHTMLVIEWER_GetRect(IHTMLViewer * pIHTMLViewer, AEERect * prc)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
prc | 要填入控件坐标的矩形。

返回值：

无

备注：

无

另请参阅：

AEERect

IHTMLVIEWER_SetRect()

返回函数列表

IHTMLVIEWER_GetViewState()

说明：

此函数用于返回表示当前浏览器状态的字符串。 将此字符串传递给 IHTMLVIEWER_SetViewState() 可恢复浏览器状态。

原型：

int IHtmlViewer_GetViewState
(
IHtmlViewer *p,
char * pszBuffer,
int cbBuffer);

参数：

pszBuffer | 指向保存结果（以零结束的字符串）的缓冲区开始位置的指针。
cbBuffer | 缓冲区的大小（以字节为单位）

返回值：

结果字符串的长度（包括零终止符）。

注意： 如果

pszBuffer 为 NULL 或 cbBuffer 为 0，

则不会写入结果字符串，而是返回需要的缓冲区大小。

备注：

无

另请参阅：

IHTMLVIEWER_SetViewState()

返回函数列表

IHTMLVIEWER_HandleEvent()

说明：

此函数用于处理控件的主要事件。 向控件传递事件时即会调用此函数。 事件主要包括按键事件。 所有控件都必须实现此函数。

原型：

boolean IHTMLVIEWER_HandleEvent
(
IHTMLViewer * pIHTMLViewer,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
evt | 事件代码。
wp | 16 位事件数据。
dwp | 32 位事件数据。

返回值：

如果控件已处理事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_IsActive()

说明：

此函数用于返回控件的激活或焦点状态。

原型：

boolean IHTMLVIEWER_IsActive(IHTMLViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

如果控件处于激活状态，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_IsBusy()

说明：

如果浏览器正从 IAStream 或 Isource 加载 HTML，此函数将返回 TRUE。

原型：

boolean IHTMLVIEWER_IsBusy(IHtmlViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

如果浏览器正忙，则返回 TRUE。

如果浏览器空闲，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_LoadSource()

说明：

此函数用于将 ISource 的内容载入文档，并将数据分析为 HTML。 先前的所有内容将被删除。 加载过程在后台异步进行，且通常无法在此函数的调用期间完成。 加载完 ISource 后，将显示文档内容。 调用程序可以通过调用 IHTMLVIEWER_IsBusy() 检查浏览器是否正忙于加载，并通过设置通知回调和监视 HVN_DONE 通知来获得加载完成的通知。 假定源数据流的字符编码是与本地电话编码相兼容的 8 位编码（ISOLATIN 1、Shift-JIS 或KSC5601）。

原型：

void IHTMLVIEWER_LoadSource(IHtmlViewer * pIHTMLViewer, ISource * ps)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
ps | 指向 ISource 对象的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_LoadStream()

说明：

此函数用于将 ISource 的内容载入文档，并将数据分析为 HTML。 先前的所有内容将被删除。 加载过程在后台异步进行，且通常无法在此函数的调用期间完成。 加载完 IAStream 后，将显示文档内容。 调用程序可以通过调用 IHTMLVIEWER_IsBusy() 检查浏览器是否正忙于加载，并通过设置通知回调和监视 HVN_DONE 通知来获得加载完成的通知。 假定源数据流的字符编码是与本地电话编码相兼容的 8 位编码（ISOLATIN 1、Shift-JIS 或KSC5601）。

原型：

void IHTMLVIEWER_LoadStream(IHtmlViewer * pIHTMLViewer, IAStream * ps)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
ps | 指向 IAStream 对象的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_ParseBuffer()

说明：

此函数用于向浏览器加载以零结束的字符串内容。 除了是以零结束的字符串，而不是以长度受限的缓冲区提供 HTML 之外，该函数与 IHTMLVIEWER_SetData() 都相当。 有关详细信息，请参阅 IHTMLVIEWER_SetData()。

原型：

void IHTMLVIEWER_ParseBuffer
(
IHtmlViewer * pIHTMLViewer,
const char * psz
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
psz | 指向包含 HTML 以零结束字符串的指针

返回值：

无

备注：

此函数实际上是一个将 cbLen 设为 -1 来调用 IHTMLVIEWER_SetData() 的宏。

另请参阅：

IHTMLVIEWER_SetData()

返回函数列表

IHTMLVIEWER_Redraw()

说明：

此函数用于刷新整个 HTML 浏览器控件。 在大量使用其它实体刷新全部或部分浏览器屏幕区域后，您可以使用此函数进行刷新。 应用程序通常不必调用此函数来确保浏览器的内容或选项发生变化之后进行屏幕更新。 在确保更改能正确反映到屏幕上的同时，浏览器会尽可能地减少不必要的刷新。

原型：

boolean IHTMLVIEWER_Redraw(IHTMLViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

如果控件已处理事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IHTMLVIEWER_AddRef()

返回函数列表

IHTMLVIEWER_Reset()

说明：

此函数用于指示控件重置（释放或删除）其内容，并立即离开激活或焦点模式。
这在通过单一调用来释放文本或菜单控件中全部基本内存或删除全部菜单项时十分
有用。

原型：

void IHTMLVIEWER_Reset(IHTMLViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

IHTMLVIEWER_SetActive()

返回函数列表

IHTMLVIEWER_SetActive()

说明：

此函数用于指示控件进入或离开焦点或选中模式。 焦点的概念主要针对控件。 对于菜单，焦点表示菜单是激活的。 对文本控件而言，则表示控件是激活的并处于编辑模式。 调用此函数通常会使基本控件刷新其内容。 即使控件处于非激活状态，仍可以调用 IHTMLVIEWER_HandleEvent() 函数，这一点十分重要。 这样可使控件处理特殊事件，例如滚动多行文本控件。

原型：

void IHTMLVIEWER_SetActive
(
IHTMLViewer * pIHTMLViewer,
boolean bActive
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
bActive | 指定激活 (TRUE) 还是停用 (FALSE) 控件。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_SetData()

说明：

此函数为浏览器提供 HTML 缓冲。 所有缓冲区均同步解析至浏览器中， 并删除先前的所有内容。 返回时，浏览器不保留指向缓冲区的指针。 假定源数据流的字符编码是与本地电话编码相兼容的 8 位编码（ISOLATIN 1、Shift-JIS 或KSC5601）。

原型：

void IHTMLVIEWER_SetData
(
IHtmlViewer * pIHTMLViewer,
const char * psz,
int cbLen
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
psz | 指向缓冲区开始位置的指针（不必以零结束）
cbLen | 缓冲区大小，或 -1。-1 表示 psz 指向以零结束的字符串，并且该字符串的所有内容均将加载至浏览器。

返回值：

无

备注：

无

另请参阅：

IHTMLVIEWER_ParseBuffer()

返回函数列表

IHTMLVIEWER_SetIndent()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_N_INDENT) 的简写函数。 用于设置基本缩进量。

原型：

int IHTMLVIEWER_SetIndent(IHtmlViewer * p, int nIndent)

参数：

p | 指向 IHtmlViewer 接口的指针。
nIndent | 默认缩进（以像素为单位）

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

此函数实际上是一个调用 IHTMLVIEWER_SetOption() 的宏。

另请参阅：

IHTMLVIEWER_SetOption().

返回函数列表

IHTMLVIEWER_SetLinkColor()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_RGB_LINK) 的简写函数。 用于设置默认文本颜色。

原型：

void IHTMLVIEWER_SetLinkColor
(
IHtmlViewer * pIHTMLViewer,
RGBVAL rgbLink
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
rgbLink | 链接的颜色

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

RGBVAL

IHTMLVIEWER_SetOption().

返回函数列表

IHTMLVIEWER_SetNotifyFn()

说明：

此函数用于指定通知回调中的信息，其中包括在调用时传递给函数的函数指针和上下文空指针。 通知回调用于通知事件的所有者，它通常是由于用户操作引起的。 处于激活状态的通知回调任何时候都不能超过一个。 设置回调将覆盖以前的任何设置。
向 pfnNotify 传递 NULL 将完全禁用通知回调。

原型：

void IHTMLVIEWER_SetNotifyFn
(
IHtmlViewer * pIHTMLViewer,
PFNHVIEWNOTIFY pfnNotify,
void * pvUser
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
pfnNotify | 指向通过通知调用的函数的指针，或者如果取消通知则为 NULL。
pvUser | 调用 pfnNotify 时（如果调用）传递给它的 32 位值。

返回值：

无

备注

无

另请参阅：

PFNHVIEWNOTIFY

返回函数列表

IHTMLVIEWER_SetOption()

说明：

此函数用于设置控制浏览器行为的多个选项中的一个。 调用程序通常不能直接调用此函数；各个选项都定义有宏。

原型：

int IHTMLVIEWER_SetOption
(
IHtmlViewer * pIHTMLViewer,
int32 nID,
HVOpt pVal
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nID | 所设置选项的 ID。
pVal | 要分配给选项的值。

返回值：

如果已分配选项，则返回 SUCCESS。

如果不支持选项 ID，则返回 EUNSUPPORTED。

备注：

无

另请参阅：

IHTMLVIEWER_SetType()

IHTMLVIEWER_SetURL()

IHTMLVIEWER_SetIndent()

IHTMLVIEWER_SetVSpace()

IHTMLVIEWER_SetSBWidth()

IHTMLVIEWER_SetTextColor()

IHTMLVIEWER_SetLinkColor()

IHTMLVIEWER_GetOption()

返回函数列表

IHTMLVIEWER_SetProperties()

说明：

此函数用于设置特定于控件的属性或标记。 尽管某些属性是跨控件（CP_FRAME 等）定义的，但大多数控件都包含一些属性以便对对象实施更具体的控制。

如果设置了 HVP_SCROLLBAR，则在文档内容超出分配给控件的矩形时，浏览器会显示滚动条。 如果文档内容未超出矩形，则不显示滚动条，但会一直保留显示滚动条的空间。 如果设置了 HVP_INLINE_EDIT，则文档中的文本输入字段获取焦点时，
可以就地对这些字段进行编辑。 否则，内嵌显示将为只读，用户要编辑内容，必须按下“选择”。

原型：

void IHTMLVIEWER_SetProperties
(
IHTMLViewer * pIHTMLViewer,
uint32 dwProps
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
dwProps | 32 位标记或属性组。

返回值：

无

备注：

无

副作用：

可能刷新控件

另请参阅：

IHTMLVIEWER_GetProperties()

返回函数列表

IHTMLVIEWER_SetRect()

说明：

此函数用于设置控件的激活屏幕坐标。 这样可能会导致控件刷新其内容。

原型：

void IHTMLVIEWER_SetRect
(
IHTMLViewer * pIHTMLViewer,
const AEERect * prc
)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
prc | 控件的绑定矩形。

返回值：

无

备注：

无

副作用：

可能刷新控件

另请参阅：

AEERect

IHTMLVIEWER_GetRect()

返回函数列表

IHTMLVIEWER_SetSBWidth()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_N_SBWIDTH) 的简写函数。 用于设置垂直滚动条的宽度。

原型：

int IHTMLVIEWER_SetSBWidth(IHtmlViewer * pIHTMLViewer, int nSBWidth)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nSBWidth | 基本段落间隔。

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_SetTextColor()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_RGB_TEXT) 的简写函数， 用于设置默认文本颜色。

原型：

int IHTMLVIEWER_SetTextColor(IHtmlViewer * pIHTMLViewer, RGBVAL rgb)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
rgbText | 文本的颜色。

返回值：

始终返回 SUCCESS。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_SetType()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_SZ_TYPE) 的简写函数，用于设置浏览器的 MIME 类型和（或）字符集。 目前，除 'text/html' 之外的其它 MIME 类型
（如果指定）为错误类型。 除支持的字符集之外的其它字符集（如果指定）为错误。

原型：

int IHtmlViewer_SetType
(
IHtmlViewer *pIHTMLViewer,
char *pszType
);

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
pszType | 指向 MIME MIME 类型字符串的指针，该字符串格式如下： "text/html；charset=iso-8859-1" 或 "charset=iso-8859-1" 注意： MIME 类型的字符串遵循 RFC2046 中说明的内容类型字段的语义。

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

IHTMLVIEWER_SetOption()

HVOPT_SZ_TYPE

返回函数列表

IHTMLVIEWER_SetURL()

说明：

此函数指定要加载至浏览器的文档的 URL 地址。 在将 HTML 加载至文档之前，必须先调用此函数。

原型：

int IHTMLVIEWER_SetURL(IHtmlViewer * pIHTMLViewer, const char * pszURL)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
pszURL | 基本 URL 字符串。

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_SetViewState()

说明：

此函数用于将 HTML 浏览器状态（如滚动位置）恢复至 IHTMLVIEWER_GetViewState() 返回字符串所代表的状态。

原型：

void IHTMLVIEWER_SetViewState
(
IHtmlViewer * pIHtmlViewer,
PCSTR pcszState
);

参数：

pIHtmlViewer | 指向 IHtmlViewer 接口对象的指针。
pcszState | 由 IHTMLVIEWER_GetViewState() 返回，代表之前浏览状态的字符串。

备注：

无

另请参阅：

IHTMLVIEWER_GetViewState()

返回函数列表

IHTMLVIEWER_SetVSpace()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_N_VSPACE) 的简写函数。用于设置垂直段落间隔。

原型：

int IHTMLVIEWER_SetVSpace(IHtmlViewer * pIHTMLViewer, int nVSpace)

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
nVSpace | 基本段落间隔（以像素为单位）。

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_SetIWeb()

说明：

此函数是 IHTMLVIEWER_SetOption (HVOPT_PTR_IWEB) 的简写函数。 用于设置浏览器要用来获取子对象的 IWeb 接口。

原型：

int IHTMLVIEWER_SetIWeb(IHtmlViewer *p, IWeb * piWeb);

参数：

pIHTMLViewer | 指向 IHtmlViewer 接口对象的指针。
piWeb | IWeb 接口指针

返回值：

SUCCESS 或 BREW 标准错误代码之一。

备注：

无

另请参阅：

无

返回函数列表

IHTMLVIEWER_Stop()

说明：

在浏览器遇忙时，您可以调用此函数使浏览器停止从 IAStream 或 ISource 加载 HTML。 停止加载文档时，会触发 HVN_DONE 通知。

原型：

void IHTMLVIEWER_Stop(IHtmlViewer * pIHTMLViewer)

参数：

pIHTMLViewer
指向 IHtmlViewer 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表


IImage 接口

IImage 接口可用于在屏幕上绘制位图图像和显示动画位图。 该接口支持 Windows 位图 (BMP) 格式以及各种设备专有的原位图格式。 IImage 接口的每个实例关联一个位图图像，这些位图图像可以从 BREW 资源编辑器创建的资源文件或直接从包含位图的文件中读取。 调用 IDISPLAY_Update() 或 IDISPLAY_UpdateEx() 函数才能更新屏幕。

BREW 默认环境为以下图像格式提供了 IIMAGE 接口：

  • PNG（可移植的网络图形）
  • Windows BMP
  • JPEG（当前仅支持连续 JPEG 格式，不支持渐变 JPEG 格式）。
  • BCI (Brew Compressed Image) - 此格式支持动画。 使用 BREW SDK 提供的 BCI 编辑工具可创建 BCI 图像。 “BCI 编辑工具”文档中提供了有关此格式的附加信息。

IImage 接口支持动画位图的显示。 动画位图由若干沿位图宽边并排的帧组成（如，包含四个 20x20 帧的位图是 80 像素宽、20像素高）。 启动动画时，IImage 将按指定的速度逐个显示图像帧。 显示完最后一帧之后，动画将从第一帧再次启动。IImage 将循环激活图像帧，直到明确终止动画或释放 IImage 接口实例。

IIMAGE_Draw() 可在屏幕的指定位置绘制位图图像。

IIMAGE_DrawFrame() 函数用于绘制单帧的动画位图。IIMAGE_GetInfo() 函数用于返回有关位图的信息，包括按像素计算的高度和宽度、颜色数目以及包含的帧数（如果是动画位图）。

IIMAGE_Start() 函数用于启动动画位图的动画，在指定屏幕坐标处显示动画帧（调用此函数之前，必须使用本节稍后说明的 IIMAGE_SetParm() 函数来定义图像中的帧数）。IIMAGE_Stop() 函数用于停止动画，并将图像最后显示的帧保留在屏幕上，直到被覆盖。

IIMAGE_SetParm() 用于设置以下图像参数值：

  • IPARM_SIZE 用于确定位图的高度和宽度。 通过缩小位图原始尺寸的这些值，可以只显示位图的一部分。 例如，将 50x50 的位图的大小设置为 40x40 时，将从图像右侧和底部分别删除 10 像素宽的窄条。
  • IPARM_OFFSET 用于确定位图原点的 x 和 y 坐标，默认情况下都是 0（零）。 通过将原点设为较大的值，可显示位图的一部分。 例如，将 50x50 位图的原点从 (0,0) 改为 (10, 10) 后，将从图像的左侧和顶端删除 10 像素宽的窄条。
  • IPARM_CXFRAME 用于设置动画位图中每帧的宽度（以像素为单位）。 启动位图动画前必须设置该参数或 IPARM_NFRAMES。 帧宽度将平均划分位图的总宽度。
  • IPARM_NFRAMES 用于设置动画位图中的总帧数。 启动位图动画前必须设置该参数或 IPARM_CXFRAME。 帧数量将平均划分位图的总宽度。 如果指定值小于或等于 0（零），将自动使用以下公式计算帧数：
\tnFrames = WidthOfImage / HeightOfImage
  • IPARM_RATE 用于设置动画速度，即显示每帧动画位图的时间间隔（毫秒）。
    默认值为 150 毫秒。
  • IPARM_ROP 用于设置光栅操作。光栅操作可以定义当前屏幕（目标位图）上的像素如何与要在屏幕上绘制的位图图像（源位图）的像素进行逻辑组合。 支持的光栅操作及其代表的像素布尔运算如下：

    • AEE_RO_OR | src | dest
AEE_RO_NOT | !src
AEE_RO_XOR | src ^ dest
AEE_RO_COPY | src
AEE_RO_TRANSPARENT | src
AEE_RO_MASK | src & dest
AEE_RO_MASKNOT | !src & dest
AEE_RO_MERGENOT | !src | dest

注意：BREW 的当前版本不支持参数 IPARM_OFFSCREEN。

使用 IImage 接口

  1. 获取 IImage 接口的实例，其中包含要显示的位图。
  2. 执行以下操作之一：
    • 如果位图包含在 BREW 资源文件中，调用 ISHELL_LoadResImage()函数返回包含指定位图的 IImage 实例指针。
    • 此外，可使用 ISHELL_LoadImage() 从文件直接加载位图格式图像。 如果位图包含在文件中，则调用 IImage 接口，并传递位图文件的文件名。 如果函数调用成功，它将返回指向 IImage 接口对象的有效指针。
    • 如果不是动画图像，调用 IIMAGE_Draw() 将在屏幕的指定位置绘制图像。 如果是动画图像，调用 IIMAGE_Start() 将在指定的屏幕位置开始动画，调用 IIMAGE_Stop() 则将终止动画。
  3. 调用 IIMAGE_Release() 释放 IImage 接口实例。

    4. 注意：如果有必要，它还会停止动画。

示例 1

IImage * pImage;
// IImage 接口指针占位符
pImage = ISHELL_LoadResImage(.....);
// 使用 ISHELL 从资源文件加载图像
IIMAGE_Draw(pIMage,x,y);
// 调用绘制方法来绘制图像

除了简单的绘图功能，IImage 接口还支持动画图像， 其中包括通常不支持动画的图像格式（如 Windows BMP）。

示例 2

IImage * pImage;
// IImage 接口指针占位符
pImage = ISHELL_LoadResImage(.....);
// 使用 ISHELL 从资源文件加载图像
// 如果图像为 BMP 格式，则可以将其划分为“帧”
// 每个都是cxFrames,每帧宽度为如下,
IIMAGE_SetParm(pImage,IPARM_CXFRAME,cxFrame,0);
IIMAGE_Start(IImage,10,10);
// 开始动画图像
// 稍后可以通过调用 IIMAGE_Stop
// 或 IIMAGE_Release 来终止动画。
IIMAGE_Stop(IImage);
// 终止动画

要包含的头文件列表

需要以下头文件：

AEEImage.h

函数列表

此接口的函数包括：

IIMAGE_AddRef()

IIMAGE_Draw()

IIMAGE_DrawFrame()

IIMAGE_DrawOffscreen()

IIMAGE_GetInfo()

IIMAGE_HandleEvent()

IIMAGE_Notify()

IIMAGE_Release()

IIMAGE_SetAnimationRate()

IIMAGE_SetDrawSize()

IIMAGE_SetFrameCount()

IIMAGE_SetFrameSize()

IIMAGE_SetOffset()

IIMAGE_SetParm()

IIMAGE_SetStream()

IIMAGE_Start()

IIMAGE_Stop()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IIMAGE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IIMAGE_Release()

返回函数列表

IIMAGE_Draw()

说明：

此函数用于在屏幕的指定位置绘制图像。

原型：

void IIMAGE_Draw(IImage * pIImage, int x, int y)

参数：

pIImage | 指向 IImage 接口对象的有效指针。
x | 指定要绘制图像的目标矩形区域左上角的 x 坐标。
y | 指定要绘制图像的目标矩形区域左上角的 y 坐标。

返回值：

无

备注：

无

另请参阅：

IIMAGE_DrawFrame()

返回函数列表

IIMAGE_DrawFrame()

说明：

此函数用于在屏幕的指定位置绘制指定的帧（包含在图像范围内）。

原型：

void IIMAGE_DrawFrame(IImage * pIImage, int nFrame, int x, int y)

参数：

pIImage | 指向要在屏幕上绘制帧的 IImage 接口对象的指针。
nFrame | 指定要绘制的帧。 帧数从 0（零）开始。如果正在动画图像，则可以传递 nFrame 值 -1 来绘制“当前”帧。
x | 指定要绘制帧的目标矩形区域左上角的 x 坐标。
y | 指定要绘制帧的目标矩形区左上角的 y 坐标。

返回值：

无

备注：

无

另请参阅：

IIMAGE_Draw()

返回函数列表

IIMAGE_DrawOffscreen()

说明：

此函数用于指定将图像绘入后台屏幕缓冲区，还是绘入主缓冲区。 此函数与使用 IIMAGE_SetParm() 参数调用 IIMAGE_SetParm() 的作用相同。

原型：

void IIMAGE_DrawOffscreen(IImage * pIImage, int offScr)

参数：

pIImage | 指向 IImage 接口的有效指针。
offScr | 如果是非零，表示应将图像绘制到后台缓冲区。 如果是零，表示应将图像绘制到主缓冲区。 只有支持双缓冲的设备才支持此功能。

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm (p, IPARM_OFFSCREEN, (int)b, 0)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_GetInfo()

说明：

此函数用于获取指定图像的信息。 这些信息将在 AEEImageInfo 数据结构中返回。

原型：

void IIMAGE_GetInfo(IImage * pIImage, AEEImageInfo * pi)

参数：

pIImage | [in] | 指向需要获取其信息的 IImage 接口对象的指针。
pi | [in/out] | 输入时，必须是指向 AEEImageInfo 数据结构的有效指针。 输出时，将使用有关该图像的有效信息填充该数据结构。 AEEImageInfo 中包含以下信息： uint16 cx; // 整个图像的宽度 uint16 cy; // 整个图像的高度 uint16 nColors; // 图像中的颜色数 uint16 nFrames; // 图像中的帧数。 默认情况下设为 1

返回值：

无

备注：

无

另请参阅：

AEEImageInfo

返回函数列表

IIMAGE_HandleEvent()

说明：

此函数用于将事件传递至 IImage 接口实例。

原型：

boolean IIMAGE_HandleEvent
(
IImage * pIImage,
AEEEvent evt,
uint16 wParam,
uint32 dwParam
)

参数：

pIImage | 指向接收事件的 IImage 接口实例的指针。
evt | 事件代码。
wParam | 16 位事件数据。
dwParam | 32 位事件数据。

返回值：

如果 IImage 实例已处理事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IIMAGE_Notify()

说明：

此函数用于注册回调函数，当 IIMAGE_SetStream() 启动的 I/O 流操作完成接收图像数据时将调用该回调函数。

原型：

void IIMAGE_Notify(IImage * pIImage, PFNIMAGEINFO pfn, void * pUser)

参数：

pIImage | 指向正从异步流接收图像数据的 IImage 接口实例的指针。
pfn | 当图像数据完全可用时，指向调用的回调函数。
pUser | 指向传递给回调函数的用户指定数据的指针。

返回值：

无

备注：

无

另请参阅：

PFNIMAGEINFO

IIMAGE_SetStream()

返回函数列表

IIMAGE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IIMAGE_AddRef()

返回函数列表

IIMAGE_SetAnimationRate()

说明：

此函数可辅助设置动画速度（以毫秒为单位）。 它与使用 IPARM_RATE 参数调用 IIMAGE_SetParm() 的作用相同。

原型：

void IIMAGE_SetAnimationRage(IImage * pIImage, int r)

参数：

pIImage | 指向 IImage 接口对象的指针。
r | 动画速度（以毫秒为单位）。

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm(p,IPARM_RATE,(int)r,0)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_SetDrawSize()

说明：

此函数可辅助设置要显示的实际图像的大小。它与使用 IPARM_SIZE 调用 IIMAGE_SetParm() 的作用相同。

原型：

void IIMAGE_SetDrawSize(IImage * pIImage, int cx, int cy)

参数：

pIImage | 指向 IImage 接口的有效指针。
cx | 图像的新宽度。
cy | 图像的新高度。

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm(p,IPARM_SIZE,(int)cx,(int)cy)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_SetFrameCount()

说明：

此函数可辅助设置图像中的帧数。它与使用 IPARM_NFRAMES 调用 IIMAGE_SetParm() 的作用相同。

原型：

void IIMAGE_SetFrameCount(IImage * pIImage, int n)

参数：

pIImage | 指向 IImage 接口的指针。
n | 帧数。

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm(p,IPARM_NFRAMES,(int)n,0)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_SetFrameSize()

说明：

此函数可辅助设置通常不支持动画的格式（如 Windows .BMP）的每帧宽度。
它与使用 IPARM_CXFRAME 调用 IIMAGE_SetParm 的作用相同。

原型：

void IIMAGE_SetFrameSize(IImage * pIImage, int cx);

参数：

pIImage | 指向 IIMage 接口的有效指针
cx | 每帧宽度

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm(p,IPARM_CXFRAME,(int)cx,0)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_SetOffset()

说明：

此函数可辅助设置要显示的整个图像内的偏移量。 它与使用 IPARM_OFFSET 参数调用 IIMAGE_SetParm() 的作用相同。

原型：

void IIMAGE_SetOffset(IImage * pIImage, int cx, int cy)

参数：

pIImage | 指向 IImage 接口的有效指针。
x | 新偏移量的 X 坐标。
y | 新偏移量的 Y 坐标。

返回值：

无

备注：

此函数是使用以下代码实现的宏：

IIMAGE_SetParm(p,IPARM_OFFSET,(int)x,(int)y)

另请参阅：

IIMAGE_SetParm()

返回函数列表

IIMAGE_SetParm()

说明：

此函数用于设置 IImage 接口对象的各种图像参数。 要设置的参数由 nParm 指定，
如： IPARM_SIZE、IPARM_OFFSET、IPARM_CXFRAME、IPARM_NFRAMES、IPARM_RATE、IPARM_ROP 或 IPARM_OFFSCREEN。 新参数值由 p1 和 p2 指定。

  • 如果 nParm 为 IPARM_SIZE，则此函数将指定要显示的图像大小。 使用 ISHELL_LoadResImage() 加载图像时将设置图像的默认大小。 如果要显示的图像必须小于从资源文件加载的实际图像，可以使用此函数更改图像的大小。
    这时，参数 p1 和 p2 可分别指定图像的新宽度和新高度。
  • 如果 nParm 为 IPARM_OFFSET，此函数将指定必须用于图像显示的整个图像内偏移量。 这时，参数 p1 和 p2 可分别指定图像偏移的 x 和 y 坐标， 默认的偏移为 (0, 0)。
  • 如果 nParm 为 IPARM_CXFRAME，此函数可将参数 p1 指定为每帧的宽度。 如果 p1 小于或等于 0（零），则帧的宽度将等于图像的高度。 此时无需使用参数 p2。
    • 注意：此图像参数仅用于通常不支持动画的格式（如 Windows BMP）， 而不适用于原来支持动画的格式。
  • 如果 nParm 为 IPARM_NFRAMES，则此函数可将参数 p1 指定为帧数。
    这时，每帧的宽度将取决于图像帧数或总的宽度。 如果 p1 小于或等于 0（零），将自动使用以下公式计算帧数：
    nFrames = WidthOfImage / HeightOfImage。
    此时不使用参数 p2。
    • 注意：此图像参数仅用于通常不支持动画的格式（如 Windows BMP）。 而不适用于原来支持动画的格式。
  • 如果 nParm 为 IPARM_RATE，此函数用于将参数 p1 指定为动画速度
    （毫秒）。 默认的动画速度是 150 毫秒。 不使用参数 p2。
    • 注意： 此图像参数仅用于通常不支持动画的格式，如 Windows BMP。 不适用于原来支持动画的格式。
  • 如果 nParm 为 IPARM_ROP，此函数可将参数 p1 指定为绘制图像时要使用的“光栅”操作。 默认的“光栅”操作是 AEE_RO_COPY。 此时无需使用参
    数 p2。
  • 如果 nParm 为 IPARM_OFFSCREEN，此函数可指定是否将图像绘入后台屏幕缓冲区。

原型：

void IIMAGE_SetParm(pImage * pIImage, int nParm, int p1, int p2)

参数：

nParm | IPARM_SIZE, IPARM_OFFSET, IPARM_CXFRAME, IPARM_NFRAMES, IPARM_RATE, IPARM_ROP 和 IPARM_OFFSCREEN。
p1 | nParm 特定参数值。
p2 | nParm 特定参数值。

返回值：

无

备注：

以下是此函数的用法示例：

  • 如果使用 ISHELL_LoadResImage() 函数加载大小为 50x60 的图像，但要在 30x40 的范围内显示图像或动画，则您需要调用：
    IIMAGE_SetParm(pIImage,IPARM_SIZE,30,40)；
  • 上例中，如果只希望看到从偏移处 (10,10) 开始的图像部分，则您需要调用：
    IIMAGE_SetParm(pIImage,IPARM_OFFSET,10,10);
  • 如果要将位图分为三个帧，则您需要调用：
    IIMAGE_SetParm(pIImage,IPARM_NFRAMES,3,0);

另请参阅：

AEE IImage 参数

返回函数列表

IIMAGE_SetStream()

说明：

此函数允许 IAStream 接口与 IImage 接口对象相关联，使图像数据从文件或套接字
流入。

原型：

void IIMAGE_SetStream (IImage * pIImage, IAStream * pIAStream)

参数：

pIImage | 指向接收图像数据流输入的 IImage 接口对象的指针。
pIAStream | 指向实现 IAStream 接口的类（如，IFile 或 ISocket）实例的指针。

返回值：

无

备注：

IIMAGE_Release()和IIMAGE_SetStream()都将释放原先的流，如果存在的话。

另请参阅：

IASTREAM_Read()

IASTREAM_Readable()

返回函数列表

IIMAGE_Start()

说明：

此函数用于使给定的图像产生动画效果。 它能够循环激活图像的每一帧。 使它们显示在由参数 x 和 y 指定的坐标处。 动画计时器显示两个连续帧之间的时间间隔设置为 150 毫秒。 动画将持续到调用 IIMAGE_Stop() 函数为止。

原型：

void IIMAGE_Start(IImage * pIImage, int x, int y)

参数：

pIImage | 指向要产生动画效果的 IImage 接口对象的指针。
x | 指定要绘制帧的目标矩形区域左上角的 x 坐标。
y | 指定要绘制帧的目标矩形区域左上角的 y 坐标。

返回值：

无

备注：

无

另请参阅：

IIMAGE_Stop()

返回函数列表

IIMAGE_Stop()

说明：

该函数用于终止使用 IIMAGE_Start() 所启动的图像动画。

原型：

void IIMAGE_Stop(IImage * pIImage)

参数：

pIImage

指向要终止动画的 IImage 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

IIMAGE_Start()

返回函数列表


IImageCtl 接口

此接口允许调用者显示图像的可滚动视图。 它本质上是 IImage 对象外的一个包装对象。


IImageCtl 的示例代码用法

IImage * pi;
IImageCtl * pvc;
CtlAddItem ci;
AEERect rc;
pi = ISHELL_LoadImage(pMe->m_pIShell,"test.bmp");
if(pi){
ISHELL_CreateInstance(pMe->m_pIShell, AEECLSID_IMAGECTL, (void **)(&pvc));
if(pvc){
MEMSET(&ci,0,sizeof(ci));
ci.pImage = pi;
rc.x = 10;
rc.y = 20;
rc.dx = rc.dy = 50;
// 告知控件绘制边框...
IIMAGECTL_SetProperties(pvc,CP_BORDER);
// 设置控件矩形。 如果需要，将绘制滚动条。
IIMAGECTL_SetRect(pvc, &rc);
// 设置控件中的图像...
IIMAGECTL_SetImage(pvc,pi);
// 告知控件它是活动的 - 处理键区事件...
IIMAGECTL_SetActive(pvc,TRUE);
// 告知它进行刷新...
IIMAGECTL_Redraw(pvc);
}
IIMAGE_Release(pi);
}
}

要包含的头文件列表

需要以下头文件：

AEEImageCtl.h

函数列表

此接口的函数包括：

IIMAGECTL_AddRef()

IIMAGECTL_GetProperties()

IIMAGECTL_GetRect()

IIMAGECTL_HandleEvent()

IIMAGECTL_IsActive()

IIMAGECTL_Redraw()

IIMAGECTL_Release()

IIMAGECTL_Reset()

IIMAGECTL_SetActive()

IIMAGECTL_SetImage()

IIMAGECTL_SetProperties()

IIMAGECTL_SetRect()

IIMAGECTL_SetRedraw()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IIMAGECTL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IIMAGECTL_Release()

返回函数列表

IIMAGECTL_GetProperties()

说明：

此方法用于返回图像控件的特定属性或标记。

原型：

uint32 IIMAGECTL_GetProperties(IImageCtl * pIImageCtl);

参数：

pIImageCtl
指向图像控件对象的指针

返回值：

图像控件的 32 位属性

备注：

无

另请参阅：

IIMAGECTL_SetProperties()

返回函数列表

IIMAGECTL_GetRect()

说明：

此方法可以将图像控件激活的屏幕坐标填入指向输入 RECT 的指针中。 在创建图像控件后确定其最佳/默认的大小和位置时，此函数特别有用。

原型：

void IIMAGECTL_GetRect(IImageCtl * pIImageCtl, AEERect * prc);

参数：

pIImageCtl | 指向图像控件对象的指针
prc | 要填入图像控件坐标的矩形

返回值：

无

备注：

无

另请参阅：

AEERect

IIMAGECTL_SetRect()

返回函数列表

IIMAGECTL_HandleEvent()

说明：

此方法用于处理图像控件的主要事件。 向图像控件传递事件时即会调用此函数。 事件主要包括按键事件。

原型：

boolean IIMAGECTL_HandleEvent
(
IImageCtl * pIImageCtl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIImageCtl | 指向图像控件对象的指针
evt | 事件代码
wp | 16 位事件数据
dwp | 32 位事件数据

返回值：

如果图像控件已处理事件，则返回 TRUE。 否则，返回 FALSE。

备注：

无

另请参阅：

AEEEvent

返回函数列表

IIMAGECTL_IsActive()

说明：

此方法用于返回图像控件的激活或焦点状态。

原型：

boolean IIMAGECTL_IsActive(IImageCtl * pIImageCtl);

参数：

pIImageCtl
指向图像控件对象的指针

返回值：

如果图像控件处于激活状态，则返回 TRUE。 否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IIMAGECTL_Redraw()

说明：

此方法用于指示图像控件刷新其内容。

原型：

boolean IIMAGECTL_Redraw(IImageCtl * pIImageCtl);

参数：

pIImageCtl
指向图像控件对象的指针

返回值：

如果图像控件已刷新，则返回 TRUE。 否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IIMAGECTL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IIMAGECTL_AddRef()

返回函数列表

IIMAGECTL_Reset()

说明：

该方法用于指示图像控件重置（释放或删除）其内容，并立即离开活动或焦点模式。

原型：

void IIMAGECTL_Reset(IImageCtl * pIImageCtl);

参数：

pIImageCtl
指向图像控件对象的指针

返回值：

无

备注：

无

另请参阅：

IIMAGECTL_SetActive

返回函数列表

IIMAGECTL_SetActive()

说明：

此方法用于指示控件进入或离开焦点或选定的模式。 对于图像控件，焦点表示图像控件是激活的。

原型：

void IIMAGECTL_SetActive(IImageCtl * pIImageCtl,boolean bActive);

参数：

pIImageCtl | 指向图像控件对象的指针
bActive | 指定是要激活 (TRUE)，还是停用 (FALSE) 图像控件。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IIMAGECTL_SetImage()

说明：

此方法设置图像控件中的图像。

原型：

void IIMAGECTL_SetImage(IImageCtl * pIImageCtl,IImage * pi););

参数：

pIImageCtl | 指向图像控件对象的指针
pi | 指向图像的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IIMAGECTL_SetProperties()

说明：

此方法可以用于设置 CP_BORDER 属性，以指示控件绘制其边框。

原型：

void IIMAGECTL_SetProperties(IImageCtl * pIImageCtl, uint32 dwProps);

参数：

pIImageCtl | 指向图像控件对象的指针
dwProps | 32 位标记或属性组

返回值：

无

备注：

无

副作用：

可能刷新图像控件。

另请参阅：

IIMAGECTL_GetProperties()

返回函数列表

IIMAGECTL_SetRect()

说明：

此方法用于设置图像控件激活的屏幕坐标。 这样可能会导致图像控件刷新其内容。

原型：

void IIMAGECTL_SetRect(IImageCtl * pIImageCtl, const AEERect * prc);

参数：

pIImageCtl | 指向图像控件对象的指针
prc | 图像控件的绑定矩形

返回值：

无

备注：

无

副作用：

可能刷新图像控件。

另请参阅：

AEERect

IIMAGECTL_GetRect()

返回函数列表

IIMAGECTL_SetRedraw()

说明：

此方法用于为图像控件中设置的图像，设置刷新回调。 如果设置了刷新回调，则图像控件中设置的图像每次需要刷新时都将调用它。

原型：

void IIMAGECTL_SetRedraw
(
IImageCtl * pIImageCtl,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIImageCtl | 指向图像控件对象的指针
pfn | 刷新回调
pUser | 用户数据

返回值：

无

备注：

先设置图像才能为它设置刷新回调。

另请参阅：

PFNNOTIFY

返回函数列表


ILicense 接口

此接口使 BREW 应用程序可以查询其应用程序模块的许可信息。 此接口的函数只适用于当前已加载或正在执行的应用程序模块。如果许可类型设置为“基于使用” (LT_USES)，则这些函数还允许 BREW 应用程序设置当前模块的许可信息。

要包含的头文件列表

需要以下头文件：

AEELicense.h

函数列表

此接口的函数包括：

ILICENSE_AddRef()

ILICENSE_DecrementUsesRemaining()

ILICENSE_GetInfo()

ILICENSE_GetPurchaseInfo()

ILICENSE_IncrementUsesRemaining()

ILICENSE_IsExpired()

ILICENSE_Release()

ILICENSE_SetUsesRemaining()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ILICENSE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ILICENSE_Release()

返回函数列表

ILICENSE_DecrementUsesRemaining()

说明：

此函数用于逐一减少应用程序的使用计数。

原型：

int ILICENSE_DecrementUsesRemaining(ILicense * pILicense)

参数：

pILicense
指向 ILicense 接口对象的指针。

返回值：

如果计数有效，则返回 SUCCESS。

如果 AEELicenseType 不属于 LT_USES，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

ILICENSE_GetInfo()

说明：

此函数返回应用于当前运行应用程序模块的许可类型。 它还提供特定于许可类型的过期信息。

每次使用需通过许可 (LT_USES) 的应用程序，必须调用此函数确定是否允许下次使用。 BREW 不严格限制对 LT_USES 应用程序的访问，是否可对该应用程序进行访问，完全取决于应用程序本身。

以下提供了支持的许可类型，以及每种许可类型相关过期值的含义：

  • LT_NONE 表示许可证不过期， 无相关的值。
  • LT_USES 表示许可证在使用应用程序指定的次数后过期， 其值为剩余使用次数。
  • LT_DATE 表示许可证在指定日期过期， 其值为过期日期或时间。
  • LT_DAYS 表示许可证在下载后数日过期， 其值为过期时间。
  • LT_MINUTES_OF_USE 表示许可证在应用程序激活数分钟后过期， 其值为剩余分钟数。

对于 LT_DAYS 和 LT_DATE，过期值是要与 GETTIMESECONDS() 进行比较的
时间值。

对于 LT_MINUTES_OF_USE，仅在应用程序退出时更新剩余分钟值。 应用程序运行期间，此函数返回的值不会发生变化。 仅当用户尝试启动应用程序时，BREW 才实施此类型的许可。 如果应用程序在执行期间过期，此时，BREW 不会执行任何操作，
允许继续执行该应用程序。 当然，应用程序可以在运行的同时监控自己的活动时间，并根据需要处理此类过期。

原型：

AEELicenseType ILICENSE_GetInfo
(
ILicense * pILicense,
uint32 * pdwInfo
)

参数：

pILicense | [in] | 指向 ILicense 接口对象的指针。
pdwInfo | [out] | 返回特定于 AEELicenseType 的过期信息。

返回值：

当前运行应用程序的许可类型。

备注：

无

另请参阅：

无

返回函数列表

ILICENSE_GetPurchaseInfo()

说明：

此函数用于返回购买应用程序的方式， 并可选择填写许可类型和过期值。 价格类型
包括：

  • PT_DEMO： 演示版
  • PT_PURCHASE： 普通购买版
  • PT_SUBSCRIPTION： 订购版
  • PT_UPGRADE： 升级

应用程序可以使用此函数检查它是否是作为“演示”版购买的。 如果应用程序是作为“演示”版购买，则它可以使用此函数禁用特定功能。

使用 ILICENSE_GetInfo() 可返回许可类型及其相关的过期值。

原型：

AEEPriceType ILICENSE_GetPurchaseInfo
(
ILicense *pILicense,
AEELicenseType * plt,
uint32 * pdwExpire,
uint32 * pdwSeq
)

参数：

pILicense | [in] | 指向 ILicense 接口对象的指针。
plt | [out] | 指向许可类型的指针
pdwExpire | [out] | 指向过期值的指针
pdwSeq | [out] | 指向已下载版本序列号的指针

返回值：

请参阅参数。

备注：

无

另请参阅：

无

返回函数列表

ILICENSE_IncrementUsesRemaining()

说明：

此函数用于逐一增加应用程序的使用计数。

原型：

int ILICENSE_IncrementUsesRemaining(ILicense * pILicense)

参数：

pILicense
指向 ILicense 接口对象的指针。

返回值：

如果计数有效，则返回 SUCCESS。

如果 AEELicenseType 不属于 LT_USES，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

ILICENSE_IsExpired()

说明：

此函数在当前模块已过期时返回 TRUE。 过期由应用程序模块上的日期值或内部计数指示，应用程序模块使用 ILICENSE_Decrement 或 ILICENSE_Increment 维护过期。 如果 AEELicenseType 为 LT_USES，此函数将始终返回 FALSE，因为过期是从应用程序内部进行管理的。

原型：

boolean ILICENSE_IsExpired(ILicense * pILicense)

参数：

pILicense
指向 ILicense 接口对象的指针。

返回值：

如果应用程序模块已过期，则返回 TRUE。

如果应用程序模块尚未过期，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ILICENSE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ILICENSE_AddRef()

返回函数列表

ILICENSE_SetUsesRemaining()

说明：

此函数用于更新应用程序的使用计数。 BREW 不会根据应用程序启动事件或任何其它事件自动更新使用计数。 使用许可 (LT_USES) 应用程序负责通过 ILICENSE 方法记录使用次数。 请参阅 ILICENSE_GetInfo()。

原型：

int ILICENSE_SetUsesRemaining(ILicense * pILicense, uint32 dwCount)

参数：

pILicense | 指向 ILicense 接口对象的指针。
dwCount | 新使用计数。

返回值：

如果计数有效，则返回 SUCCESS。

如果 AEELicenseType 不属于 LT_USES，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表


IMedia 接口

IMedia 接口类为所有 BREW 多媒体对象提供了一个抽象基类。 它可以提供一种多媒体格式或通过特定设备播放的格式。 例如，执行 MIDI 播放的 IMediaMIDI 对象和渲染 MPEG4 内容的 IMediaMPEG4 对象。 BREW 多媒体对象可以包含音频、视频和卡拉 OK 文本的组合。 IMedia 接口可提供播放、录音以及执行播放或录音控制函数（如定位、停止、暂停、恢复等）等功能。注意： 今后，基于 IMedia 的对象就是指 IMedia 接口对象。


外壳注册：

IMedia 接口对象的基类 ID 为 AEECLSID_MEDIA。 对于处理给定 MIME 的基于 IMedia 类，-您需要使用此类 ID 来查询外壳注册。 通常，IMedia 接口句柄均使用 MIME 类型注册："audio/" 和"video/"。IMedia MIME 类型的完整列表，请参考 AEEMIMETypes.h。


创建 IMedia 接口对象

可以通过以下两种方法之一创建 IMedia 接口对象：

  1. 如果已知类 ID，则可以使用基于 IMedia 类的类 ID，或者
  2. 使用 AEEMediaUtil.c 中提供的 AEEMediaUtil_CreateMedia() 实用程序函数，以分析媒体数据、检测媒体数据类型（即为其 MIME）、获取该 MIME 的注册类 ID（使用 AEECLSID_MEDIA 作为基类）并创建 IMedia 接口对象。

在第一种情况下，IMedia 接口对象处于“空闲”状态。 在“空闲”状态下无法使用 IMedia 接口对象。 您需要使用 IMEDIA_SetMediaData() 设置媒体数据，如果设置成功，它将使 IMedia 接口对象进入“就绪”状态。

在第二种情况下，AEEMediaUtil_CreateMedia() 将使 IMedia 接口对象进入“就绪”状态。


回调事件：

IMedia 接口中的多数操作为异步操作。 如果要接收 IMedia 接口对象中的事件，您需要使用 IMEDIA_RegisterNotify() 注册回调通知函数。 这一步是可选的。 您可以使用若干 IMedia 对象注册一个回调函数。 也可以使用 IMedia 指针或回调数据中返回的类 ID 建立相互联系。


IMedia 状态机：

IMedia 可以维护以下基本状态机。 IMedia 的实现程序可以扩展状态机。

注意：

(1) IMEDIA_SetMediaData() 用于设置媒体数据。 设备中尚未加载媒体数据。

(1) IMEDIA_Play() 或 IMEDIA_Record() 用于加载媒体数据、分配所需的设备多媒体资源以及开始播放或录音。

(2) IMEDIA_Stop() 用于停止当前播放或录音、释放所有设备多媒体资源以及将处于任何播放或录音状态的 IMedia 置为“就绪”状态。


删除 IMedia 对象：

最好应将 IMedia 对象释放。 但 BREW 不强制执行此操作。 卸载应用程序时，BREW 将停止正在进行的播放或录音，并清除 IMedia 对象以及所有相关的设备多媒体资源。


同时播放或录音：

BREW 对同时播放或录音无硬性规定。 它取决于基于 IMedia 类的实现程序以及设备功能。
例如，基于 QUALCOMM MSM5100 的设备通常支持一个 MIDI/QCP 背景播放以及通过 MIDI 输出设备同时进行的四个 QCP 播放。 BREW 指定的唯一要求是，如果不支持某个 IMedia API，则该 API 将返回 EUNSUPPORTED。


应用程序中止和恢复事件处理：

如果应用程序得到 EVT_APP_SUSPEND，则它最好执行 IMEDIA_Stop() 并释放与 IMedia 对象相关的所有资源。 您可以不必执行 IMEDIA_Release()，但我们建议您在得到 EVT_APP_RESUME 后释放 IMedia 对象，然后重新创建它（以及相关资源）。

要包含的头文件列表

需要以下头文件：

AEEMedia.h

函数列表

IMEDIA_AddRef()

IMEDIA_FastForward()

IMEDIA_GetClassID()

IMEDIA_GetMediaData()

IMEDIA_GetMediaParm()

IMEDIA_GetRect()

IMEDIA_GetState()

IMEDIA_GetTotalTime()

IMEDIA_GetVolume()

IMEDIA_Pause()

IMEDIA_Play()

IMEDIA_QueryInterface()

IMEDIA_Record()

IMEDIA_RegisterNotify()

IMEDIA_Release()

IMEDIA_Resume()

IMEDIA_Rewind()

IMEDIA_Seek()

IMEDIA_SetAudioDevice()

IMEDIA_SetAudioPath()

IMEDIA_SetMediaData()

IMEDIA_SetMediaParm()

IMEDIA_SetMuteCtl()

IMEDIA_SetPan()

IMEDIA_SetRect()

IMEDIA_SetTickTime()

IMEDIA_SetVolume()

IMEDIA_Stop()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IMEDIA_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表。

IMEDIA_Release()

返回函数列表

IMEDIA_FastForward()

说明：

此函数用于从当前位置快进 ITimeMS 毫秒。 媒体保持当前状态。

原型：

int IMEDIA_FastForward(iname * pIMedia, int32 lTimeMS)

参数：

pIMedia | 指向 IMedia 接口对象的指针
lTimeMS | 时间（以毫秒为单位）

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误。

EBADSTATE： 当前状态下无法定位。

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API。

备注：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_SEEK 或 MM_SEEK_FAIL 状态。

另请参阅：

IMEDIA_Seek()

IMEDIA_Rewind()

IMEDIA_Play()

返回函数列表

IMEDIA_GetClassID()

说明：

此函数用于检索 IMedia 接口对象的类 ID。

原型：

int IMEDIA_GetClassID(IMedia * pIMedia, AEECLSID * pCls)

参数：

pIMedia | [in] | 指向 IMedia 接口对象的指针
pCls | [out] | IMedia 对象的类 ID

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 当前状态下无法获取参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_GetMediaData()

说明：

此函数用于获取媒体数据。

原型：

int IMEDIA_GetMediaData(IMedia * pIMedia, AEEMediaData * pmd)

参数：

pIMedia | [in] | 指向 IMedia 接口对象的指针
pmd | [out] | 媒体数据

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_GetMediaParm()

IMEDIA_SetMediaData()

IMEDIA_SetMediaParm()

返回函数列表

IMEDIA_GetMediaParm()

说明：

该函数用IMEDIA_SetMediaParm()获取参数集合。

原型：

int IMEDIA_GetMediaParm
(
iname * pIMedia,
int nParamID,
int32 * pP1,
int32 * pP2
)

参数：

pIMedia | 指向 IMedia 接口对象的指针
nParmID | MM_PARM_XXX
pP1 | 取决于参数
pP2 | 取决于参数

返回值：

如果成功，则返回 SUCCESS

MM_PENDING： 在注册回调中返回值

否则，将返回错误代码：

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

下表将给出 IMedia 接口支持的可设置参数列表：

nParmID | Op | Desc | p1 | p2
MM_PARM_MEDIA_DATA | 获取/设置 | 媒体数据 | AEEMediaData |
MM_PARM_AUDIO_DEVICE | 获取/设置 | 音频设备 | AEESoundDevice |
MM_PARM_AUDIO_PATH | 获取/设置 | 媒体路径 | MM_APATH_XXX SilenceTimerMS。 仅用于振铃器路径： （默认值为 1000 ms）， 播放间隔。 如果为 0，表示不重复。 |
MM_PARM_VOLUME | 获取/设置 | 音量控制 | 音量 (0-AEE_MAX_VOLUME) |
MM_PARM_MUTE | 获取/设置 | 静音控制 | 0 表示静音，1 表示取消静音 |
MM_PARM_TEMPO | 获取/设置 | 速度控制 | 速度系数（百分比） |
MM_PARM_TUNE | 获取/设置 | 音调控制 | 音调系数 |
MM_PARM_PAN | 获取/设置 | 相位控制 | 相位系数： 范围： [0（左）< 64（平衡位置 - 默认设置）< 128（右）] |
MM_PARM_TICK_TIME | 获取/设置 |  | 周期为 1000（默认设置）；如果为 0，则表示不发送任何事件 |
MM_TICK_UPDATE |  |  | 事件 |
MM_PARM_RECT | 获取/设置 | 视频/图像和目标视频/图像 | AEERect * 目标文本 | AEERect * 文本矩形
MM_PARM_PLAY_REPEAT | 获取/设置 | 重复播放次数 | 1 表示播放一次（默认设置）； 0 表示不停播放； n>1 表示播放 n 次
MM_PARM_CAPS | 获取 | 用于获取 IMedia 功能。 | OR 功能标记。 已定义的标记为： MM_CAPS_AUDIO、MM_CAPS_VIDEO 和 MM_CAPS_TEXT | IMedia 的特定功能结构 *
MM_PARM_ENABLE | 获取/设置 | 用于启用或禁用特定的 IMedia 功能。 例如，您可能要在 PMD 播放期间禁用视频。 | OR 功能标记。 已定义的标记为： MM_CAPS_AUDIO、MM_CAPS_VIDEO 和 MM_CAPS_TEXT | 未使用

副作用：

此函数的返回值可能为 MM_PENDING。 在这种情况下，结果将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。

另请参阅：

IMEDIA_SetMediaParm()

AEEMediaCmdNotify

返回函数列表

IMEDIA_GetRect()

说明：

此函数用于检索目标图像矩形和文本矩形。

原型：

int IMEDIA_GetRect
(
IMedia * pIMedia,
AEERect * prImage,
AEERect * prText
)

参数：

pIMedia | [in] | 指向 IMedia 接口对象的指针
prImage | [out] | 图像矩形指针
prText | [out] | 文本矩形指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

AEERect

IMEDIA_Play()

IMEDIA_Record()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_GetState()

说明：

此函数用于返回 IMedia 接口的当前状态，并指示 IMedia 接口对象当前是否正在转换状态。

原型：

int IMEDIA_GetState(iname * pIMedia, boolean * pbStateChanging)

参数：

pIMedia | 指向 IMedia 接口对象的指针
pbStateChanging | TRUE 表示 IMedia 接口当前正在进行状态转换。

返回值：

MM_STATE_XXX

备注：

无

副作用：

如果 IMedia 接口当前正进行状态转换，则多数 IMedia 函数将失败，并返回 EBADSTATE。

另请参阅：

无

返回函数列表

IMEDIA_GetTotalTime()

说明：

此函数用于返回 IMedia 接口对象的播放时间总量。

原型：

int IMEDIA_GetTotalTime(iname * pIMedia)

参数：

pIMedia
指向 IMedia 接口对象的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误。

EBADSTATE： IMedia 未就绪。

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API。

备注：

IMEDIA_GetTotalTime() 只能工作于“就绪”状态。

副作用：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_DONE 或 MM_RESUME_ABORT 状态。

另请参阅：

AEEMediaCmdNotify

返回函数列表

IMEDIA_GetVolume()

说明：

此函数用于检索当前播放或录音的音量。

原型：

int IMEDIA_GetVolume(IMedia * pIMedia, uint16 * pwVolume)

参数：

pIMedia | [in] | 指向 IMedia 接口接口对象的指针
pwVolume | [out] | 指向音量的指针。

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_SetAudioPath()

IMEDIA_SetMuteCtl()

IMEDIA_SetVolume()

IMEDIA_SetPan()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

IMEDIA_SetAudioDevice()

返回函数列表

IMEDIA_Pause()

说明：

此函数用于暂停媒体，并在 MM_STATUS_PAUSE 回调中返回当前位置。

原型：

int IMEDIA_Pause(iname * pIMedia)

参数：

pIMedia
指向 IMedia 接口对象的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_PAUSE 或 MM_PAUSE_FAIL 状态。

另请参阅：

IMEDIA_Play()

IMEDIA_Resume()

IMEDIA_Record()

AEEMediaCmdNotify

返回函数列表

IMEDIA_Play()

说明：

此函数用于开始播放 IMedia 接口对象。 它将加载媒体数据、分配所需设备多媒体资源并开始播放。

原型：

int IMEDIA_Play(IMedia * pIMedia)

参数：

pIMedia
指向 IMedia 接口对象的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_EBADSTREAM： 流错误

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

这些播放事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 和 AEEMediaData
文档。

另请参阅：

IMEDIA_FastForward()

IMEDIA_Pause()

IMEDIA_Record()

IMEDIA_Resume()

IMEDIA_Rewind()

IMEDIA_Seek()

IMEDIA_Stop()

AEEMediaCmdNotify

返回函数列表

IMEDIA_QueryInterface()

说明：

此函数可用于

(1) 获取指向基于输入类 ID 的接口或数据的指针

(2) 查询 IMedia 派生类的扩展版本

(3) 支持版本兼容

原型：

int IMEDIA_QueryInterface
(
IMedia * pIMedia,
AEECLSID clsReq,
void ** ppo
)

参数：

pIMedia | [in] | 指向 IMedia 接口对象的指针。
clsReq | [in] | 标识正在尝试查询的实体（接口或数据）的全局唯一 id。
ppo | [out] | 指向要检索的接口或数据的指针。 如果传递回来的值为 NULL，则表示要查询的接口或数据不存在。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

备注：

如果 ppo 为 NULL 指针，则接口或查询数据不可用。

副作用：

如果检索接口，则此函数将增加其引用计数。 如果检索数据结构，则将给出指向内部结构的指针，且用户不能将其释放。

另请参阅：

无

返回函数列表

IMEDIA_Record()

说明：

开始对 IMedia 接口对象进行录音。 它将加载媒体数据、分配所需设备多媒体资源并开始录音。

原型：

int IMEDIA_Record(IMedia * pIMedia)

参数：

pIMedia
指向 IMedia 接口对象的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_EBADSTREAM： 流错误

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

录音事件将在注册回调中返回，请参阅 AEEMediaCmdNotify 和 AEEMediaData 文档。

另请参阅：

IMEDIA_FastForward()

IMEDIA_Pause()

IMEDIA_Play()

IMEDIA_Resume()

IMEDIA_Rewind()

IMEDIA_Seek()

IMEDIA_Stop()

AEEMediaCmdNotify

AEEMediaData

返回函数列表

IMEDIA_RegisterNotify()

说明：

此函数用于通过 IMedia 接口对象注册回调通知函数。IMedia 接口将通过此回调报告异步事件。

原型：

int IMEDIA_RegisterNotify
(
IMedia * pIMedia,
PFNMEDIANOTIFY pfnNotify,
void * pUser
)

参数：

pIMedia | 指向 IMedia 接口对象的指针
pfnNotify | 指向回调函数的指针。
pUser | 调用 pfnNotify() 时使用的用户数据

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADSTATE： 错误 - IMedia 接口未处于空闲状态。

备注：

无

另请参阅：

PFNMEDIANOTIFY

返回函数列表

IMEDIA_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMEDIA_AddRef()

返回函数列表

IMEDIA_Resume()

说明：

此函数用于从当前位置恢复媒体，并在 MM_STATUS_RESUME 回调中返回当前位置。

原型：

int IMEDIA_Resume(iname * pIMedia)

参数：

pIMedia | 指向 IMedia 接口对象的指针
lTimeMS | 时间（以毫秒为单位）

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_RESUME 或 MM_RESUME_FAIL 状态。

另请参阅：

IMEDIA_Play()

IMEDIA_Pause()

IMEDIA_Record()

AEEMediaCmdNotify

返回函数列表

IMEDIA_Rewind()

说明：

此函数用于从当前位置倒退 ITimeMS 毫秒。 媒体保持当前状态。

原型：

int IMEDIA_Rewind(iname * pIMedia, int32 lTimeMS)

参数：

pIMedia | 指向 IMedia 接口对象的指针
lTimeMS | 时间（以毫秒为单位）

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_SEEK 或 MM_SEEK_FAIL 状态。

另请参阅：

IMEDIA_FastForward()

IMEDIA_Seek()

IMEDIA_Play()

AEEMediaCmdNotify

返回函数列表

IMEDIA_Seek()

说明：

此函数用于根据 eSeek 和 ITimeMS 参数来定位媒体位置。 媒体保持当前状态。

原型：

int IMEDIA_Seek(iname * pIMedia, AEEMediaSeek eSeek, int32 lTimeMS)

参数：

pIMedia | 指向 IMedia 接口对象的指针。
eSeek | 定位引用。
lTimeMS | 时间（以毫秒为单位）。

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADPARM： 流中的参数错误

EBADSTATE： 当前状态下无法播放

EITEMBUSY： IMedia 接口当前正忙。 请稍后再试。

EUNSUPPORTED： 该类不支持此 API

备注：

这些事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_SEEK 或 MM_SEEK_FAIL 状态。

另请参阅：

AEEMediaSeek

IMEDIA_FastForward()

IMEDIA_Rewind()

IMEDIA_Play()

返回函数列表

IMEDIA_SetAudioDevice()

说明：

此函数用于设置媒体数据，并将媒体置为“就绪”状态。

原型：

int IMEDIA_SetAudioDevice(IMedia * pIMedia, AEESoundDevice eDevice)

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
eDevice | 目标音频设备

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注回调中返回值。

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_SetAudioPath()

IMEDIA_SetMuteCtl()

IMEDIA_SetVolume()

IMEDIA_GetVolume()

IMEDIA_SetPan()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_SetAudioPath()

说明：

此函数用于设置播放或录音的音频路径。

原型：

int IMEDIA_SetAudioPath(IMedia * pIMedia, int nAPath uint32 dwMS);

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
nAPath | 音频路径
dwMS | 振铃音间的停顿（以毫秒为单位）。 仅用于 MM_APATH_LOCAL_RINGER。

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

音频路径可以取以下值：

MM_APATH_LOCAL | 播放至 录音自 | 听筒、扬声器等 话筒
MM_APATH_LOCAL_RINGER | 播放至 | 振铃器
MM_APATH_REMOTE | 播放至 录音自 | ReverseLink（无线）。 ForwardLink。
MM_APATH_BOTH | 播放 [至] | MM_APATH_LOCAL MM_APATH_TX。

另请参阅：

IMEDIA_SetMuteCtl()

IMEDIA_SetVolume()

IMEDIA_GetVolume()

IMEDIA_SetPan()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

IMEDIA_SetAudioDevice()

返回函数列表

IMEDIA_SetMediaData()

说明：

此函数用于设置媒体数据，并将媒体置为“就绪”状态。

原型：

int IMEDIA_SetMediaData(IMedia * pIMedia, AEEMediaData * pmd)

参数：

pIMedia | 指向 IMedia 接口对象的指针
pmd | 媒体数据

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 无法获取当前状态下的参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_GetMediaData()

IMEDIA_GetMediaParm()

IMEDIA_SetMediaParm()

返回函数列表

IMEDIA_SetMediaParm()

说明：

此函数用于设置指定的 IMedia 接口对象参数。

原型：

int IMEDIA_SetMediaParm
(
iname * pIMedia,
int nParamID,
int32 p1,
int32 p2
)

参数：

pIMedia | 指向 IMedia 接口对象的指针
nParmID | MM_PARM_XXX
p1 | 取决于参数
p2 | 取决于参数

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 当前状态下无法设置参数

EUNSUPPORTED： 该类不支持此参数

备注：

下表将给出 IMedia 接口支持的可设置参数列表：

nParmID | Op | Desc | p1 | p2
MM_PARM_MEDIA_DATA | 获取/设置 | 媒体数据 | AEEMediaData |
MM_PARM_AUDIO_DEVICE | 获取/设置 | 音频设备 | AEESoundDevice |
MM_PARM_AUDIO_PATH | 获取/设置 | 媒体路径 | MM_APATH_XXX SilenceTimerMS。 仅用于振铃器路径： （默认值为 1000 ms）， 播放间隔。 如果为 0，表示不重复。 |
MM_PARM_VOLUME | 获取/设置 | 音量控制 | 音量 (0-AEE_MAX_VOLUME) |
MM_PARM_MUTE | 获取/设置 | 静音控制 | 0 表示静音，1 表示取消 静音 |
MM_PARM_TEMPO | 获取/设置 | 速度控制 | 速度系数（百分比） |
MM_PARM_TUNE | 获取/设置 | 音调控制 | 音调系数 |
MM_PARM_PAN | 获取/设置 | 相位控制 | 相位系数： 范围： [0（左）< 64（平衡位置 - 默认设置）< 128（右）] |
MM_PARM_TICK_TIME | 获取/设置 |  | 周期为 1000（默认设置）；如果为 0，则表示不发送任何事件 |
MM_TICK_UPDATE |  |  | 事件 |
MM_PARM_RECT | 获取/设置 | 视频/图像和目标视频/图像 | AEERect * 目标文本 | AEERect * 文本矩形
MM_PARM_PLAY_REPEAT | 获取/设置 | 重复播放次数 | 表示播放一次（默认设置）； 0 表示不停播放； n>1 表示播放 n 次
MM_PARM_CAPS | 获取 | IMedia 类 OR 功能 | MM_CAPS_XXX | IMedia 的特定功能结构 *
MM_PARM_ENABLE | 获取/设置 | 启用或禁用 IMedia OR 功能 | MM_CAPS_XXX |

副作用：

此函数的返回值可能为 MM_PENDING。 在这种情况下，结果将在注册回调中返回。
请参阅 AEEMediaCmdNotify 文档。

另请参阅：

AEEMediaData

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_SetMuteCtl()

说明：

此函数用于对当前音频路径设置静音或取消静音。

原型：

int IMEDIA_SetAudioPath(IMedia * pIMedia, boolean bMute)

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
bMute | TRUE 表示静音 否则，表示未静音

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值。

EBADPARM： 参数错误。

EBADSTATE： 当前状态下无法获取参数。

EUNSUPPORTED： 该类不支持此参数。

备注：

无

另请参阅：

IMEDIA_SetAudioPath()

IMEDIA_SetVolume()

IMEDIA_GetVolume()

IMEDIA_SetPan()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

IMEDIA_SetAudioDevice()

返回函数列表

IMEDIA_SetPan()

说明：

此函数用于设置当前播放的相位系数。

原型：

int IMEDIA_SetPan(IMedia * pIMedia, uint16 wPan)

参数：

pIMedia
指向 IMedia 接口接口对象的指针
wPan
相位系数。 范围：
  • 0（零）表示（左）。
  • MM_MAX_PAN/2 表示（平衡位置-默认设置）。
  • MM_MAX_PAN 表示（右）。

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值。

EBADPARM： 参数错误。

EBADSTATE： 当前状态下无法获取参数。

EUNSUPPORTED： 该类不支持此参数。

备注：

无

另请参阅：

IMEDIA_SetAudioPath()

IMEDIA_SetMuteCtl()

IMEDIA_SetVolume()

IMEDIA_GetVolume()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

IMEDIA_SetAudioDevice()

返回函数列表

IMEDIA_SetRect()

说明：

此函数用于设置目标图像矩形和文本矩形。 如果媒体数据包含视频或图像信息，则它将在指定的图像矩形中显示。 如果媒体数据包含嵌入式文本信息，则该文本将在文本矩形中显示。

原型：

int IMEDIA_SetRect
(
IMedia * pIMedia,
AEERect * prImage,
AEERect * prText
)

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
prImage | 图像矩形指针
prText | 文本矩形指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 当前状态下无法获取参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

AEERect

IMEDIA_Play()

IMEDIA_Record()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_SetTickTime()

说明：

此函数用于设置在播放或录音期间向应用程序发送 MM_TICK_UPDATE 事件的周期。

原型：

int IMEDIA_SetTickTime(IMedia * pIMedia, uint32 wTickMS)

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
dwTickMS | 定时周期。 1000（默认设置）；0 表示不发送任何事件。

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 当前状态下无法获取参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_Play(),

IMEDIA_Record()

IMEDIA_SetMediaParm(),

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_SetVolume()

说明：

此函数用于设置当前播放或录音的音量。

原型：

int IMEDIA_SetVolume(IMedia * pIMedia, uint16 wVolume)

参数：

pIMedia | 指向 IMedia 接口接口对象的指针
wVolume | 音量。 范围： 0 - AEE_MAX_VOLUME

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 在注册回调中返回值

EBADPARM： 参数错误

EBADSTATE： 当前状态下无法获取参数

EUNSUPPORTED： 该类不支持此参数

备注：

无

另请参阅：

IMEDIA_SetAudioDevice()

IMEDIA_SetAudioPath()

IMEDIA_SetMuteCtl()

IMEDIA_GetVolume()

IMEDIA_SetPan()

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

返回函数列表

IMEDIA_Stop()

说明：

此函数用于停止对 IMedia 接口对象进行播放或录音。 它将释放所有设备多媒体资源，并将 IMedia 接口从任何播放或录音状态置为“就绪”状态。

原型：

int IMEDIA_Stop(IMedia * pIMedia)

参数：

pIMedia
指向 IMedia 接口对象的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

EBADSTATE： 当前状态下无法停止

备注：

这些录音事件将在注册回调中返回。 请参阅 AEEMediaCmdNotify 文档。 此函数将把对象置为 MM_STATUS_DONE 状态。

另请参阅：

IMEDIA_Play()

IMEDIA_Record()

返回函数列表


IMedia 格式

本节将定义从 IMedia 类派生的以下接口：

  • IMediaMIDI 接口： 播放标准 MIDI 格式 (SMF)
  • IMediaMIDIOutMsg 接口： 播放 MIDI 消息
  • IMediaMIDIOutQCP 接口： 使用 MIDI 设备播放前景中的 QCP (PureVoice) 文件
  • IMediaMP3 接口： 播放 MP3 格式
  • IMediaQCP 接口： 播放和录制 QCP (PureVoice) 格式
  • IMediaPMD 接口： 播放包含同步音频和视频的 PMD 格式

要包含的头文件列表

MediaFormats 系列接口需要以下头文件：

AEEMediaFormats.h

接口和函数列表

此接口系列中包括以下接口和函数

IMediaMIDI 接口

IMediaMIDIOutMsg 接口

IMEDIAMIDIOUTMSG_SetMIDIMsg()

IMediaMIDIOutQCP 接口

IMediaMP3 接口

IMediaQCP 接口

IMEDIAQCP_GetFormat()

IMEDIAQCP_SetFormat()

IMediaPMD 接口


IMediaMIDI 接口

此接口用于处理标准 MIDI 格式的播放。 这种格式的接口没有相关函数。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

使用 IMedia 接口和函数列表。

返回接口和函数列表


IMediaMIDIOutMsg 接口

此接口用于将 MIDI 消息直接交付到 MIDI 输出设备。 这种格式的接口没有相关函数。 通常不需要直接使用此接口的 API，而是使用 IMedia API。 只有需要执行特定于该接口的操作时，
才使用它的 API。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

IMEDIAMIDIOUTMSG_SetMIDIMsg()

使用 IMedia 接口和函数列表。

返回接口和函数列表

IMEDIAMIDIOUTMSG_SetMIDIMsg()

说明：

此函数用于将包含 MIDI 消息的缓冲区设置为媒体数据缓冲区。

原型：

int IMEDIAMIDIOUTMSG_SetMIDIMsg
(
IMedia * pIMedia,
uint8 * pMsgBuf,
uint32 dwSize
)

参数：

pIMedia | 指向 IMedia 接口对象的指针
pMsgBuf | 包含 MIDI 消息的缓冲区
dwSize | 缓冲区的大小

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 已注册回调所返回的值

EBADPARM： 错误的 Parm

EBADSTATE： 无法获取当前状态下的 Parm

EUNSUPPORTED： 该类不支持 Parm

备注：

必须在开始播放之前调用此 API。

另请参阅：

IMEDIAQCP_SetFormat()

IMEDIAQCP_GetFormat()

返回接口和函数列表


IMediaMIDIOutQCP 接口

此接口可通过 MIDI 输出设备处理 QCP 格式的播放。 通常不需要直接使用此接口的 API，
而是使用 IMedia API。 只有需要执行特定于该接口的操作时，才使用它的 API。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

使用 IMedia 接口和函数列表。

返回接口和函数列表


IMediaMP3 接口

此接口可处理 MP3 格式的播放。这种格式的接口没有相关函数。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

使用 IMedia 接口和函数列表。

返回接口和函数列表


IMediaQCP 接口

此接口可处理 QCP (PureVoice) 格式的播放和录音。 通常不需要直接使用此接口的 API，而是使用 IMedia API。 只有需要执行特定于该接口的操作时，才使用它的 API。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

IMEDIAQCP_SetFormat()

IMEDIAQCP_GetFormat()

返回接口和函数列表

IMEDIAQCP_GetFormat()

说明：

此函数用于检索 QCP 格式。

原型：

int IMEDIAQCP_GetFormat(IMedia * pIMedia, int * pnFormat);

参数：

pIMedia | [in] | 指向 IMedia 接口对象的指针
pnFormat | [out] | 指向 QCP 格式的指针

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 已注册回调返回的值

EBADPARM： 错误的 Parm

EBADSTATE： 无法获取当前状态下的 Parm

EUNSUPPORTED： 该类不支持 Parm

备注：

*pnFormat 可以为以下值：

MM_QCP_FORMAT_FIXED_FULL_13K： 固定全速率，13K 声码器

MM_QCP_FORMAT_VAR_FULL_13K： 可变速率，最大全速率 13K

MM_QCP_FORMAT_EVRC： 可变速率，最大全速率 EVRC

MM_QCP_FORMAT_VAR_FULL_13K： 可变速率，最大半速率 13K

MM_QCP_FORMAT_UNKNOWN： 未知格式

另请参阅：

IMEDIA_GetMediaParm()

IMEDIA_SetMediaParm()

返回接口和函数列表

IMEDIAQCP_SetFormat()

说明：

此函数用于设置 QCP 格式，主要用于录音。

原型：

int IMEDIAQCP_SetFormat(IMedia * pIMedia, int nFormat);

参数：

pIMedia： 指向 IMedia 接口对象的指针

nFormat： QCP 格式

返回值：

如果成功，则返回 SUCCESS

否则，将返回错误代码：

MM_PENDING： 已注册回调返回的值

EBADPARM： 错误的 Parm

EBADSTATE： 无法获取当前状态下的 Parm

EUNSUPPORTED： 该类不支持 Parm

备注：

nFormat 可以为以下值：

MM_QCP_FORMAT_FIXED_FULL_13K： 固定全速率，13K 声码器

MM_QCP_FORMAT_VAR_FULL_13K： 可变速率，最大全速率 13K

MM_QCP_FORMAT_EVRC： 可变速率，最大全速率 EVRC

MM_QCP_FORMAT_VAR_FULL_13K： 可变速率，最大半速率 13K

MM_QCP_FORMAT_UNKNOWN： 未知格式

另请参阅：

IMEDIAQCP_GetFormat()

返回接口和函数列表


IMediaPMD 接口

此接口用于处理包含音频、视频和卡拉 OK 文本的 PMD (WebAudio) 格式的播放。 这种格式的接口没有相关函数。 通常不需要直接使用此接口的 API，而是使用 IMedia API。 只有需要
执行特定于该接口的操作时，才使用它的 API。

要包含的头文件列表

需要以下头文件：

AEEMediaFormats.h

函数列表

此接口的函数包括：

使用 IMedia 接口和函数列表。

返回接口和函数列表


IMemAStream 接口

IMemAStream 接口可以扩展 IAStream 接口，以允许将指定的内存块作为流读入。 IMemAStream 实例可由 ISHELL_CreateInstance() 使用 ClassID AEECLSID_MEMASTREAM 创建。 释放 IMemAStream 接口对象时将释放指定的内存块。

除了标准 IBase 接口函数，AddRef() 和 Release()，以及标准 IAStream 接口函数，Readable()、Read() 和 Cancel() 以外，IMemAStream 接口中还包括 Set() 函数。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

该接口的函数包括：

IMEMASTREAM_AddRef()

IMEMASTREAM_Cancel()

IMEMASTREAM_Read()

IMEMASTREAM_Readable()

IMEMASTREAM_Release()

IMEMASTREAM_Set()

IMEMASTREAM_SetEx()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IMEMASTREAM_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMEMASTREAM_Release()

返回函数列表

IMEMASTREAM_Cancel()

说明：

此函数用于取消以前使用 IMEMASTREAM_Readable() 注册的通知函数。

原型：

void IMEMASTREAM_Cancel
(
IMemAStream * pIMemAstream,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIMemAstream | 指向 IMemAStream 接口对象的指针。
pfn | 指向用户函数的指针，该函数在 IMEMASTREAM_Readable() 中设置为通知函数。
pUser | 指向用户数据的指针，调用 pfn 时提供该数据作为参数。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IMEMASTREAM_Readable()

返回函数列表

IMEMASTREAM_Read()

说明：

此函数用于将 pIMemAStream 流中的 nBytes 字节读入目标缓冲区 pDest。 如果流中的字节数少于 nBytes，该函数将返回实际读取的字节数。

此函数尝试从使用 IMEMASTREAM_Set() 设置到 IMemAStream 接口对象中的缓冲区读取数据。 因此，在调用此函数之前，必须调用 IMEMASTREAM_Set() 在 IMemAStream 接口对象中设置有效的内存缓冲区。

原型：

int32 IMEMASTREAM_Read
(
IMemAStream * pIMemAstream,
void * pDest,
uint32 nBytes
)

参数：

pIMemAstream | 指向 IMemAStream 接口对象的指针。
pDest | 指向读取数据的缓冲区的指针。
nBytes | 要从流中读取的字节数。

返回值：

读取的字节数

备注：

如果 nBytes 大于使用 IMEMASTREAM_Set() 设置的缓冲区中的数据量，则仅读取缓冲区中的可用数据，并返回该数量。

另请参阅：

IMEMASTREAM_Set()

返回函数列表

IMEMASTREAM_Readable()

说明：

此函数允许指定函数 pfn，当流中有可以读取的数据时，IMemAStream 接口对象将使用该函数来通知您。 对于 IMemAStream 接口对象，由于从使用 IMEMASTREAM_Set() 调用的内存缓冲区中读取数据，因此将立即尝试回调。

原型：

void IMEMASTREAM_Readable
(
IMemAStream * pIMemAstream,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIMemAstream | 指向 IMemAStream 接口对象的指针。
pfn | 指向用户函数的指针，当有数据可供读取时，IMemAStream 接口对象必须调用该函数。
pUser | 指向用户数据的指针，调用 pfn 时该数据必须作为参数使用。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

返回函数列表

IMEMASTREAM_Release()

说明：

此函数用于减少 IMemAStream 接口对象的引用计数。 引用计数为 0（零）时，将从内存中释放该对象且不再有效。 引用计数为 0（零）时，同时还将释放之前通过调用 IMEMASTREAM_Set() 设置的内存缓冲区。

原型：

uint32 IMEMASTREAM_Release(IMemAstream * pIMemAstream)

参数：

pIMemAstream
指向 IMemAStream 接口对象的指针。

返回值：

已减少的对象引用计数。

如果该对象已被释放，且不再有效，则返回 0（零）。

备注：

无

另请参阅：

IMEMASTREAM_Set()

返回函数列表

IMEMASTREAM_Set()

说明：

该函数可以设置需要作为流读取的内存块。 IMemAStream 接口对象的实例必须已经存在。

IMemAStream 接口负责释放缓冲区 pBuff。 但请不要释放该缓冲区。 在发生以下两种操作之一时，再将其释放：

  • 使用 IMEMASTREAM_Release() 释放了 IMemAStream 接口对象。
  • 随后，尝试使用其它缓冲区来调用 IMEMASTREAM_Set()。

如果以前调用该函数时已经在流中设置了缓冲区，则在设置新的缓冲区之前将释放该缓冲区。

注意：使用同一缓冲区连续两次调用 IMEMASTREAM_Set() 是很危险的。

原型：

void IMEMASTREAM_Set
(
IMemAStream * pIMemAStream,
byte * pBuff,
uint32 dwSize,
uint32 dwOffset,
boolean bSysMem
)

参数：

pIMemAStream | 指向 IMemAStream 接口 对象的指针。
pBuff | 指向需要作为流读取的内存块的指针。
dwSize | 内存块的大小。
dwOffset | 从内存块起始位置的偏移量，设置为内存流的起始数据。
bSysMem | 指定缓冲区内存 pBuff 属于用户区域还是系统内存的标记。 此标记可以指示在释放 IMemAStream 接口对象或使用另一个 Set() 时，该对象必须使用常规 FREE() 还是 SYSFREE() 来释放该缓冲区。 例如，如果执行 MALLOC() 来分配缓冲区， 则 bSysMem 必须设置为 FALSE。

返回值：

无

备注：

无

另请参阅：

IMEMASTREAM_Release()

返回函数列表

IMEMASTREAM_SetEx()

说明：

此函数与 IMEMASTREAM_Set() 的功能相同，但增加了一个用于释放内存块的用户回调功能。 您可以指定回调函数 pUserFreeFn，以便在需要释放内存块 pBuff 时调用该
函数。

原型：

void IMEMASTREAM_SetEx
(
IMemAStream * pIMemAStream,
byte * pBuff,
uint32 dwSize,
uint32 dwOffset,
PFNNOTIFY pUserFreeFn,
void * pUserFreeData
)

参数：

pIMemAStream | 指向 IMemAStream 接口的指针。
pBuff | 指向需要作为流读取的内存块的指针。
dwSize | 内存块的大小。
dwOffset | 从内存块起始位置的偏移量，设置为内存流的起始数据。
pUserFreeFn | 需要释放内存块时调用的回调函数。
pUserFreeData | 将传递给 pUserFreeFn 的参数。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IMEMASTREAM_Set()

返回函数列表


IModule 接口

IModule 接口提供了控制访问一组相关小程序或组件的机制。 该模块为 AEE 外壳提供了单一的入口点来请求模块中的类。 大多数情况下，模块显露单个小程序或共享组件的类。 但是，IModule 接口允许模块在没有固定入口点时显露各种类。 该模块还可以作为所有相关对象的基对象，这样模块便可以通过模块类的私有实现来共享内存和其它资源。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

该接口的函数包括：

IMODULE_AddRef()

IMODULE_CreateInstance()

IMODULE_FreeResources()

IMODULE_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IMODULE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMODULE_Release()

返回函数列表

IMODULE_CreateInstance()

说明：

此函数为 AEE 提供了根据需要从模块中请求类的机制。 在成功创建请求的对象类之后，模块返回引用计数为正的类对象。

注意： 所请求的类必须按照为其指定的类定义来实现。

原型：

int IMODULE_CreateInstance
(
IModule * pIModule,
IShell * pIShell,
AEECLSID ClsId,
void * * ppObj
)

参数：

pIModule | [in] | 指向 IModule 接口对象的指针。
pIShell | [in] | 指向 IShell 接口对象的指针。
ClsId | [in] | 所请求的 ClassID（由模块显露）。
ppObj | [out] | 返回的对象。 由 IMODULE_CreateInstance() 函数填写。

返回值：

如果对象类已创建，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的类，则返回 EBADCLASS。

备注：

对象返回时的引用计数必须为正。

另请参阅：

AEECLSID 列表

返回函数列表

IMODULE_FreeResources()

说明：

如果外壳或设备检测到内存或存储空间不足，AEE 外壳将调用该函数。 这些情况包括 RAM 或闪存/文件存储空间不足。 根据所涉及的具体情况，传递给模块的指针可以指向 IHeap 接口 或 IFileMgr 接口。 在此条件下，模块将释放所有未使用的 RAM 或文件存储空间。

原型：

void IMODULE_FreeResources
(
IModule * pIModule,
IHeap * ph,
IFileMgr * pfm
)

参数：

pIModule | 指向 IModule 接口对象的指针。
ph | 指向 IHeap 接口对象的指针。
pfm | 指向 IFileMgr 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IMODULE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMODULE_AddRef()

返回函数列表


IMenuCtl 接口

菜单控件允许设备用户从项目列表中进行选择。 使用“向上”、“向下”、“向左”和“向右”箭头键可以指定当前选择的菜单项，已选择的菜单项将在屏幕上突出显示。 如果设备用户按下“选择”键，并启用发送命令（参见本节后面的内容），EVT_COMMAND 将发送给创建菜单的应用程序或对话框，其中包括当前选项的标识符。 菜单控件有以下四种类型：

  • 标准菜单控件 (ClassID AEECLSID_MENUCTL) 可以在屏幕上分行显示菜单项，
    每行都包含菜单项的图标或文本字符串。 如果屏幕不能容纳所有的菜单项，可使用“向上”和“向下”箭头键上下滚动菜单。
  • 列表控件 (ClassID AEECLSID_LISTCTL) 仅在屏幕上显示当前已选的菜单项。 在应用程序的可用屏幕区有限时，此类菜单非常有用。 列表控件菜单项仅包含文本
    （不包含图像）。 请使用“向上”和“向下”箭头键定位到指定的菜单项。
  • 软键菜单控件 (ClassID AEECLSID_SOFTKEYCTL) 可以沿屏幕的底部并排显示菜单项。 请使用“向左”和“向右”箭头键指定已选菜单项。 软键菜单控件包含图标和（或）文本字符串。
  • 图标视图菜单控件 (ClassID AEECLSID_ICONVIEWCTL) 使用位图图标表示每个菜单项。 屏幕上显示一行或多行位图图标，可使用箭头键在行间和每行的图标间移动。 对应于当前已选菜单项的文本字符串则显示在屏幕的底部。

创建菜单控件实体时，请通过指定其 ClassID 选择所需的类型。 如上所述，IMENUCTL_HandleEvent() 处理“向上”、“向下”、“向左”和“向右”箭头键以及
“选择”键。 这些菜单还可以处理字符事件。 如果将 EVT_CHAR 消息传递给活动菜单，它将搜索以该字母（区分大小写）开始文本的菜单条目。 这种选择类型只适用于单个字符。 如果到最后一个项目的末尾仍未找到该选项，则上卷菜单。 如果没有匹配项，则不更改选择。
如果项目没有与之关联的文本，则跳过该项目。 如果指定了日程视图菜单（如下所述），标准菜单控件也处理用于输入日程约会时间的设备数字键（AVK_0 至 AVK_9）。 除了软键菜单之外，设备用户按下“向左”和“向右”键时，菜单控件将发送控件切换事件 (EVT_CTL_TAB)。 如果按下“向上”或“向下”键，则软键菜单将发送控件切换事件。
使用控件切换可在多控件屏幕中的控件间移动。 如果菜单控件是对话框的一部分，对话框将截获控件切换事件并相应地更改控件焦点。

菜单控件支持若干可使用 IMENUCTL_SetProperties() 设置的属性。 以下属性名称是用于获取和设置属性的位掩码常量名称：

  • MP_WRAPSCROLL 引起滚动上卷（例如如果选择最后一个菜单项并按“向下”键，则将选中第一个菜单项）。 该属性始终适用于软键和列表控件菜单。
  • MP_NO_ARROWS 仅适用于“图标视图”菜单，并为其设置 MP_ICON_SINGLE_FRAME 属性， 以防止在项目文本的任一侧绘制箭头。
  • MP_NO_REDRAW 在每次更改选择的菜单项或设置激活菜单时，禁止刷新菜单。
  • MP_MAXSOFTKEYITEMS 增至 12 项，它是屏幕上一次可以显示的软键菜单项数目。 默认情况下，最多显示三项。
  • MP_CALENDAR

    • 该属性允许在日程程序中使用标准菜单作为“日期视图”。 菜单项目（约会时间）具有以下未说明的特性：

    • 在菜单项之间绘制水平线，每项表示特定钟点的日程约会。
    • 如果左上角出现小方框，则表示下午。 没有方框则表示上午。
    • 在菜单的右边缘绘制将一个三角形，指示相对于通过 IMENUCTL_SetItemTime() 设置的菜单项目 wMinStart 的当前时间。
    • 菜单项目的高度与通过 IMENUCTL_SetItemTime()() 设置的 wDuration 值成正比。

      • 使用设备的数字键选择约会钟点，应用程序还可设置说明约会的菜单项文本。

  • MP_AUTOSCROLLTIME 可自动滚动“日程视图”菜单，以便在显示日程时出现与当前时间对应的条目。 只有当使用 bActive=TRUE 调用 IMENUCTL_SetActive() 且菜单当前“未”激活时，才会出现这种情况。 之后还需要调用 IMENUCTL_Redraw()。
  • MP_ICON_TEXT_TOP 使“图标视图”菜单中当前选定项目的文本字符串显示在屏幕的顶部（而不是底部）。
  • MP_ICON_SINGLE_FRAME 仅显示屏幕上当前选定菜单项的图标。 默认情况下，“图标视图”菜单按行按列显示所有图标，并突出显示选定的图标。
  • MP_UNDERLINE_TITLE 为菜单标题加下划线。
  • MP_MULTI_SEL 允许在一个菜单上选择多个项目。 用户按下菜单项目的“选择”键时，可以在不同选项间切换。 这些按下的键不会向应用程序发送 EVT_COMMAND 消息。 小程序将处理 EVT_CTL_TAB 控件切换消息，以便将焦点设置为其它控件或收集相关数据。
  • MP_BI_STATE_IMAGE 确保选择的菜单或软键项与未选择的菜单或软键项看起来有所不同。
  • MP_TRI_STATE_IMAGE 确保选择的菜单或软键、按下的菜单或软键和未选择的菜单或软键项看起来彼此不同。
  • MP_ICON_ANIMATED 确保选择的动画类型图标或方框图像能够产生动画效果。

除了 IControl 接口中的函数之外，菜单控件还实现了其它若干函数。IMENUCTL_SetTitle() 用于指定在菜单矩形顶部绘制的菜单标题值。IMENUCTL_EnableCommand() 在设备用户按下“选择”键时，启用或禁用向应用程序发送 EVT_COMMAND 事件（默认情况下，启用发送命令）。IMENUCTL_SetStyle 用于自定义菜单中的已选择项和未选择项外观，包括特殊像素边界、每项周围的填充空间和其它外观元素。

创建菜单后必须指定菜单中包含的项目。IMENUCTL_AddItem() 用于将项目添加至不包含位图图标的菜单中。 调用此函数时，要指定项目的文本字符串（从资源文件获取或在代码中定义）、整数项目 ID 以及可选的双字数据指针。 当设备用户选择该项目时，将使用 EVT_COMMAND 事件调用应用程序的 IAPPLET_HandleEvent() 函数；并将项目 ID 和双字指针指定为该函数调用的 wParam 和 dwParam 参数。IMENUCTL_AddItemEx() 是 IMENUCTL_AddItem() 的扩展版本，可提供所添加菜单项目的相关附加信息，包括其位图图标和用于显示其文本字符串的字体。IMENUCTL_DeleteItem() 删除具有特定 ID 的菜单项目，IMENUCTL_DeleteAll() 则删除菜单中的所有项目。

IMENUCTL_GetSel() 用于返回当前已选择菜单项的项目 ID。 如果没有通过按“选择”键获取设备用户的选择，则可以使用此函数。 例如，您可以在包含菜单控件的对话框终止后获取设备用户的选择。IMENUCTL_SetSel() 指定将作为当前选中项目的 ID。 菜单控件通常根据设备用户所按的箭头键确定该项，但可以使用 IMENUCTL_SetSel() 指定首次显示菜单时最初选择的项目。

IMENUCTL_GetItemData() 用于获取菜单项的双字数据指针。

IMENUCTL_SetItemText() 用于更改现有菜单项的文本字符串。

IMENUCTL_SetItemTime() 用于设置与日程菜单（参见上文）中项目相关联的起始时间和持续时间，IMENUCTL_GetItemTime() 则用于获取日程菜单项的时间信息。

创建和使用菜单控件

  1. 调用 ISHELL_CreateInstance() 创建菜单控件实例并获取其接口指针，通过其 ClassID 从四种菜单控件类型中指定所需的一种。
  2. 调用 IMENUCTL_SetTitle() 指定菜单标题，并调用 IMENUCTL_AddItem() 或 IMENUCTL_AddItemEx() 将各个项目添加到菜单中。
  3. 调用 IMENUCTL_SetRect() 定义要在其中绘制菜单的屏幕矩形。
  4. 调用 IMENUCTL_SetProperties() 设置所有菜单控件属性，并调用 IMENUCTL_SetStyle 自定义菜单项的外观。
  5. 完全指定了菜单控件的内容和属性后，调用 IMENUCTL_SetActive() 函数在屏幕上绘制控件并使之能够接收设备用户按键事件。 菜单控件处于活动状态中时，应用程序的 IAPPLET_HandleEvent() 函数必须调用 IMENUCTL_HandleEvent() 将所有已处理的按键事件传递给菜单控件处理。
  6. 确定如何获取设备用户的菜单选择。 如果在设备用户按下“选择”键时处理选择，则 IAPPLET_HandleEvent() 函数将包含接收到 EVT_COMMAND 时处理每个菜单项选择的逻辑。 如果应用程序从多个控件接收 EVT_COMMAND 事件，确保传入 wParam 参数的项目 ID 是唯一的。 如果在其它时间接收设备用户的选择，此时必须调用 IMENUCTL_GetSel() 或 IMENUCTL_GetItemData() 访问当前已选择的菜单项及其双字数据（如果有）。
  7. 如果不再需要菜单控件，可调用 IMENUCTL_Release() 函数将其释放。

要包含的头文件列表

需要以下头文件：

AEEMenu.h

函数列表

此接口的函数包括：

IMENUCTL_AddItem()

IMENUCTL_AddItemEx()

IMENUCTL_AddRef()

IMENUCTL_DeleteAll()

IMENUCTL_DeleteItem()

IMENUCTL_EnableCommand()

IMENUCTL_EnumNextSel()

IMENUCTL_EnumSelInit()

IMENUCTL_GetFocus()

IMENUCTL_GetItem()

IMENUCTL_GetItemCount()

IMENUCTL_GetItemData()

IMENUCTL_GetItemID()

IMENUCTL_GetItemTime()

IMENUCTL_GetProperties()

IMENUCTL_GetRect()

IMENUCTL_GetSel()

IMENUCTL_HandleEvent()

IMENUCTL_IsActive()

IMENUCTL_MoveItem()

IMENUCTL_Redraw()

IMENUCTL_Release()

IMENUCTL_Reset()

IMENUCTL_SetActive()

IMENUCTL_SetColors()

IMENUCTL_SetFocus()

IMENUCTL_SetItem()

IMENUCTL_SetItemText()

IMENUCTL_SetItemTime()

IMENUCTL_SetProperties()

IMENUCTL_SetRect()

IMENUCTL_SetSel()

IMENUCTL_SetSelEx()

IMENUCTL_SetStyle

IMENUCTL_SetTitle()

IMENUCTL_Sort()

IMENUCTL_SortCustom()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IMENUCTL_AddItem()

说明：

此函数用于向菜单添加新的菜单项。 标识菜单的文本字符串可从资源文件或使用 pText 参数指定。

如果 pText 为有效字符串，则该函数将使用此字符串作为项目名称。

如果 pText 为 NULL，则该函数将从资源文件读取对应于给定资源标识符 wResID 的字符串并将其设置为项目名称。

如果文本字符串和资源信息均无效，则此函数将会失败。

如果 pText 字段中的文本字符串和资源文件信息均有效，则 pText 参数字段将优先用作菜单项的名称。

如果 IMenuCtl 接口标识的对象是软键菜单，则此函数还将确定新项目在 x 轴方向的长度以及软键栏上能够显示的最大项目数。

lData 可用于保存与所创建菜单项相关的双字数据值。 IMENUCTL_GetItemData() 可用于获取参数值。

原型：

boolean IMENUCTL_AddItem
(
IMenuCtl * pIMenuCtl,
const char * pszResFile,
uint16 wResID,
uint16 nItemID,
AECHAR * pText,
uint32 lData
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pszResFile | 以 NULL 结尾且包含资源文件名称的字符串。
wResID | 标识文本字符串资源的资源标识符。
nItemID | 项目标识符，唯一标识菜单项。
pText | 以 NULL 结尾且包含菜单项名称的字符串。
lData | 与菜单项相关的项目数据。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

此函数不能自动更新屏幕。 要让设备屏幕上的新菜单项生效，请使用 IMENUCTL_Redraw()。 如果添加菜单项后要激活该菜单，无需使用 IMENUCTL_Redraw()，因为 IMENUCTL_SetActive() 将使用新菜单项更新屏幕。
使用 IMENUCTL_DeleteItem() 可删除菜单中的项目。

副作用：

如果设备用户激活新添加的菜单项，则 nItemID 和 lData 的值将分别发往小程序事件处理函数的短数据字段和长数据字段。

另请参阅：

IMENUCTL_DeleteItem()

IMENUCTL_Redraw()

IMENUCTL_SetActive()

返回函数列表

IMENUCTL_AddItemEx()

说明：

此函数用于向菜单、列表或图标视图添加项目。 CtlAddItem 参数指示新项目的属性。

如果 pai->pText 为有效字符串，则函数将使用此字符串作为项目名称。

如果 pai->pText 为 NULL，则函数将读取 pai->wText 和 pai-> pszResText 关联的给定资源标识符所对应的字符串。 如果读取失败，函数将返回 FALSE。

如果 pai->pImage 为有效的 IImage，函数将调用 IIMAGE_AddRef() 并使用该图像。
这样就允许调用程序释放图像对象。

如果 pai->pText 字段中的文本字符串和资源文件信息均有效，pai->pText 将优先用作菜单项的名称。

如果 pai->pImage 为 NULL，并且指定了 pai->wImage，函数将尝试从指定资源加载图像。 如果图像加载失败，函数将返回 FALSE。

原型：

boolean IMENUCTL_AddItemEx(IMenuCtl * pIMenuCtl, CtlAddItem * pai)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pai | 指向 CtlAddItem 结构的指针。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

此函数不能自动更新屏幕。 要让设备屏幕上的新菜单项生效，请使用 IMENUCTL_Redraw()。 如果添加菜单项后要激活该菜单，无需使用 IMENUCTL_Redraw()，因为 IMENUCTL_SetActive() 可使用新菜单项更新屏幕。

副作用：

如果设备用户激活新添加的菜单项，则 nItemID 和 lData 的值将分别发往小程序事件处理函数的长数据字段和短数据字段。

另请参阅：

IMENUCTL_Redraw()

IMENUCTL_AddItem()

IMENUCTL_AddItemEx()

返回函数列表

IMENUCTL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMENUCTL_Release()

返回函数列表

IMENUCTL_DeleteAll()

说明：

此函数用于从菜单控件对象删除所有的菜单项。

原型：

boolean IMENUCTL_DeleteAll(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

调用此函数时不会更新设备屏幕。 要更新设备屏幕，请使用 IMENUCTL_Redraw()。

另请参阅：

无

返回函数列表

IMENUCTL_DeleteItem()

说明：

此函数用于从菜单控件对象删除一个菜单项。 nItemID 参数用于标识要删除的菜单项。 然后函数将刷新整个菜单。

原型：

boolean IMENUCTL_DeleteItem(IMenuCtl * pIMenuCtl,uint16 nItemID)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
nItemID | 菜单项标识符，将菜单项添加到菜单时使用。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

IMENUCTL_EnableCommand()

说明：

当菜单控件对象收到设备用户按下 SELECT 键生成的事件时，此函数将使该对象向 AEE 外壳发送指定命令。

原型：

void IMENUCTL_EnableCommand(IMenuCtl * pIMenuCtl, boolean bEnable)

参数：

pIMenuCtl | 指向菜单控件对象 IMenuCtl 接口的指针。
bEnable | 启用或禁用标记。

返回值：

无

备注：

根据制造商或型号，“选择”键位于设备上不同的实际位置。 设备用户按下此键时，小程序将收到事件类型 AVK_SELECT。

另请参阅：

IMENUCTL_HandleEvent()

返回函数列表

IMENUCTL_EnumNextSel()

说明：

此函数只能用于多选菜单 (MP_MULTI_SEL)。 它可以获取下一个选定项目的 ID。

原型：

uint16 IMENUCTL_EnumNextSel(IMenuCtl * pIMenuCtl);

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针

返回值：

下一个选定项目的 ID。 没有选择其它项目时将返回值 (uint16)-1。 使用多选菜单时，
应避免使用该值作为项目 ID。

备注：

无

另请参阅：

IMENUCTL_EnumSelInit()

返回函数列表

IMENUCTL_EnumSelInit()

说明：

此函数只能用于多选菜单 (MP_MULTI_SEL)。 它可以初始化具有选项的菜单项目
枚举。

原型：

boolean IMENUCTL_EnumSelInit(IMenuCtl * pIMenuCtl);

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

在调用 IMENUCTL_EnumNextSel() 之前“必须”调用此函数

另请参阅：

IMENUCTL_EnumNextSel()

返回函数列表

IMENUCTL_GetFocus()

说明：

此函数只能用于多选菜单 (MP_MULTI_SEL)。 它可以获取具有用户输入焦点的菜单项目的项目 ID。

原型：

uint16 IMENUCTL_GetFocus(IMenuCtl * pIMenuCtl);

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针

返回值：

具有用户输入焦点的项目 ID。

备注：

无

另请参阅：

IMENUCTL_SetFocus()

返回函数列表

IMENUCTL_GetItem()

说明：

此函数查询与菜单项目关联的所有相关值，包括以下字段：

图像

图像 ID（如果基于资源）

图像文件名

文本

项目 ID

数据

字体

返回的所有对象和指针均为菜单控件所有。 如果使用这些对象和指针，调用程序将复制对象或增加对象的引用计数。 例如，如果要使用返回的图像指针，则调用程序应对其调用 IIMAGE_AddRef()。 完成后，如果不再需要指针，调用程序还必须调用 IIMAGE_Release()。

原型：

boolean IMENUCTL_GetItem
(
IMenuCtl * pIMenuCtl,
uint16 wID,
CtlAddItem * pai
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
wID | 菜单项 ID。
pai | 项目信息结构。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

CtlAddItem

IMENUCTL_SetItem()

返回函数列表

IMENUCTL_GetItemCount()

说明：

此函数用于返回菜单中的项目数。

原型：

int IMENUCTL_GetItemCount(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

菜单项数量。

备注：

无

另请参阅：

IMENUCTL_GetItemID()

返回函数列表

IMENUCTL_GetItemData()

说明：

此函数用于获取给定菜单控件对象中菜单项的相关数据。 nItemID 参数用于标识从中请求数据的菜单项。

原型：

boolean IMENUCTL_GetItemData
(
IMenuCtl * pIMenuCtl,
uint16 nItemID,
uint32 * plData
)

参数：

pIMenuCtl | [in] | 指向 IMenuCtl 接口对象的指针。
nItemID | [in] | 将此项目添加到菜单时使用的菜单项标识符。
plData | [out] | 项目数据的占位符。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

所获取的数据与添加菜单项时的菜单相关。 有关菜单项数据的详细信息，请参阅 IMENUCTL_AddItem()。

另请参阅：

IMENUCTL_AddItem()

返回函数列表

IMENUCTL_GetItemID()

说明：

此函数用于返回给定项目索引的项目 ID。

原型：

uint16 IMENUCTL_GetItemID(IMenuCtl * pIMenuCtl, int nIdx)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
nIdx | 项目索引。

返回值：

项目 ID。

备注：

无

另请参阅：

无

返回函数列表

IMENUCTL_GetItemTime()

说明：

如果菜单控件是日程，此函数将获取菜单项 ID 指定的菜单项的起始时间和持续时间（结束时间和起始时间之间的差额）。

原型：

int IMENUCTL_GetItemTime
(
IMenuCtl * pIMenuCtl,
uint16 nItemID,
uint16 * pwDuration
)

参数：

pIMenuCtl | [in] | 指向 IMenuCtl 接口对象的指针。
nItemID | [in] | 菜单项标识符。
pwDuration | [out] | 持续时间（分钟）。

返回值：

IMENUCTL_SetItemTime() 中设置的起始时间。

如果无法找到菜单项，则返回 -1。

备注：

无

另请参阅：

IMENUCTL_SetItemTime()

返回函数列表

IMENUCTL_GetProperties()

说明：

此函数用于获取菜单控件的特定属性或标记。

原型：

uint32 IMENUCTL_GetProperties(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

以下是为菜单控件对象定义的 32 位属性：

如果设置了 MP_WRAPSCROLL，则滚动到屏幕末端时将上卷循环（仅用于软键和列表控件）。

如果设置了 MP_NO_ARROWS，即使可以滚动也没有箭头（用于图标视图）。

MP_MAXSOFTKEYITEMS，每屏最多可以显示的软键项目数。

如果设置了 MP_NO_REDRAW，则不在 IMENUCTL_SetActive() 函数内部或更改选择时调用 IMENUCTL_Redraw()。

如果设置了 MP_PAGESCROLL，则按页滚动；否则为平滑滚动。

以下是仅为菜单控件对象的图标视图定义的属性：

MP_ICON_TEXT_TOP，图标视图： 文本位于顶部。

MP_ICON_SINGLE_FRAME，图标视图： 单边框。

MP_UNDERLINE_TITLE，菜单： 标题有下划线。

如果设置了 MP_ICON_ANIMATED，则动画选定的图标。 如果设置了 MP_ICON_ANIMATED 属性，并且图像形状的宽度恰好为高度的倍数，则将根据宽度与高度的倍数把图像分成方块并制成动画。 例如： 如果图像宽为 80 高为 20，且设置了 MP_ICON_ANIMATED 属性，则此图像将被分成 4 帧 20X20 的方形并制成动画。

以下是仅为菜单控件对象的日程视图定义的两个属性：

MP_CALENDAR（参见插图）允许用作日程程序菜单项（约会）“日期视图”
的标准菜单具有以下特性

  • 如果左上角出现小方框，则表示下午。 无方框则表示上午。
  • 在菜单的右边缘绘制一个三角形，指示相对于通过 IMENUCTL_SetItemTime() 设置的菜单项目 wMinStart 的当前时间。
  • 菜单项目的高度与通过 IMENUCTL_SetItemTime() 设置的 wDuration 值成
    正比。

    • 如果设置了 MP_AUTOSCROLLTIME，则指定在日程视图中设置自动滚动。 只有当使用 bActive=TRUE 调用 IMENUCTL_SetActive() 且菜单当前未激活时，才会出现这种情况。 此后还必须调用 IMENUCTL_Redraw()。

以下是仅为标准菜单或软键控件对象定义的属性：

如果设置了 MP_BI_STATE_IMAGE，没有边框的图像将有两种状态（未选择或已选择）。

如果设置了 MP_TRI_STATE_IMAGE，没有边框的图像将有三种状态（未选择、已选择或按下）。

属性只对软键和纯菜单控件有效

如果设置了 MP_MULTI_SEL，则允许按下多个条目。

备注：

无

另请参阅：

IMENUCTL_SetProperties()

返回函数列表

IMENUCTL_GetRect()

说明：

此函数用于返回菜单控件对象的控件矩形值。 要在创建控件对象后确定其最佳或默认大小和位置时，此函数非常有用。

原型：

void IMENUCTL_GetRect(IMenuCtl * pIMenuCtl, AEERect * prc)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
prc | 要填入菜单控件矩形坐标的矩形。

返回值：

无

备注：

菜单控件对象在屏幕的矩形区域内显示，而该区域由保存在菜单控件对象中的坐标指定。 默认情况下，这些坐标对应于实例化菜单控件对象时整个显示屏幕的坐标。 使用 IMENUCTL_SetRect() 可更改这些坐标，以包含显示屏幕的任意部分。 使用 IMENUCTL_GetRect() 可获取控件矩形当前的规格。

另请参阅：

AEERect

IMENUCTL_SetRect()

返回函数列表

IMENUCTL_GetSel()

说明：

此函数用于获取菜单控件对象当前选择的菜单项标识符。

原型：

uint16 IMENUCTL_GetSel(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

返回 IMenuCtl 接口对象当前菜单项选择的 ID。

备注：

它将获取选择项的位置，而不是具有 MP_MULTI_SEL 的菜单的选定属性。

另请参阅：

IMENUCTL_SetSel()

返回函数列表

IMENUCTL_HandleEvent()

说明：

菜单控件对象使用此函数处理接收的事件。 活动的菜单控件对象可以处理按键、设置标题以及添加项目事件。 非活动菜单控件对象只可以处理设置标题和添加项目事件。 菜单控件对象处理的典型按键按下事件是“向上”、“向下”、“向左”和“向右”
按键。 如果菜单控件对象已启用发送命令，则当收到通过按下“选择”按键生成的事件时，它将把命令事件发送到 AEE 外壳。

原型：

boolean IMENUCTL_HandleEvent
(
IMenuCtl * pIMenuCtl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
evt | 事件代码。
wp | 16 位事件数据。
dwp | 32 位事件数据。

返回值：

如果 IMenuCtl 接口对象已处理该事件，则返回 TRUE。

如果尚未处理该事件，则返回 FALSE。

备注：

小程序使用该菜单控件事件处理程序来处理与菜单有关的设备用户输入。 例如，当设备用户按下向下箭头键从一个菜单项选择移动到其它选择，菜单控件事件处理程序将处理该事件。 这种情况下，小程序事件处理程序函数接收相应的事件。 此时，小程序事件处理程序能调用菜单控件对象事件处理程序处理该事件。 如果小程序事件处理程序没有调用菜单控件事件处理程序，该事件将得不到处理。

根据制造商或型号，“选择”键位于设备上不同的实际位置。 设备用户按下此键时，小程序将收到 AVK_SELECT 类型的事件字参数 wParam。

另请参阅：

IMENUCTL_EnableCommand()

返回函数列表

IMENUCTL_IsActive()

说明：

此函数用于返回菜单控件对象的激活或非激活状态。

原型：

boolean IMENUCTL_IsActive(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

如果菜单控件处于激活状态，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

IMENUCTL_SetActive()

返回函数列表

IMENUCTL_MoveItem()

说明：

此函数用于在指定方向上将菜单项移动一个位置。

原型：

void IMENUCTL_MoveItem(IMenuCtl * pIMenuCtl, uint16 nItemID, int nDir);

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针
nItemID
菜单项标识符
nDir
方向：
  • -1：向上
  • 1：向下

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IMENUCTL_Redraw()

说明：

此函数用于指示菜单控件对象刷新其内容。 菜单控件对象并非在每次更改菜单控件后底层数据时都刷新其内容，目的在于同时更新若干数据，使屏幕闪烁降至最低。
例如，可更改一些菜单控件对象的内容但不生成可见的效果，直到调用“刷新”
函数。

原型：

boolean IMENUCTL_Redraw(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

如果已刷新菜单控件，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

菜单控件对象在屏幕的矩形区域内显示，而该区域由保存在菜单控件对象中的坐标指定。 默认情况下，这些坐标对应于实例化菜单控件对象时整个显示屏幕的坐标。 使用 IMENUCTL_SetRect() 可更改这些坐标，以包含显示屏幕的任意部分。 使用 IMENUCTL_Redraw() 函数仅刷新当前菜单控件对象矩形坐标规格所绑定屏幕区域内的菜单。

另请参阅：

无

返回函数列表

IMENUCTL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IMENUCTL_AddRef()

返回函数列表

IMENUCTL_Reset()

说明：

此函数用于指示菜单控件清除（释放或删除）其内容，并立即离开激活或焦点模式。 清除菜单控件对象将删除菜单中的菜单项，以及与菜单相关的标题。

原型：

void IMENUCTL_Reset(IMenuCtl * pIMenuCtl)

参数：

pIMenuCtl
指向 IMenuCtl 接口对象的指针。

返回值：

无

备注：

清除菜单控件对象不会更新设备屏幕，因此，与菜单相关的所有图形仍会保留在设备屏幕上。 要将菜单从设备屏幕上删除，请使用菜单控件对象的 IMENUCTL_Redraw()。

副作用：

清除菜单控件对象不处理任何收到的设备用户事件，如“向上”、“向下”、“向左”和“向右”箭头键按下事件。

另请参阅：

IMENUCTL_SetActive()

IMENUCTL_Redraw()

返回函数列表

IMENUCTL_SetActive()

说明：

此函数用于激活或停用菜单控件对象。 只有激活的菜单控件对象才能处理发送给它的事件。 未激活的菜单控件对象将忽略这些事件。

注意：如果指定的激活状态不符合菜单的当前状态，此函数将刷新菜单控件。
因此，如果调用函数后状态未更改，调用 IMENUCTL_SetActive() 不会刷新菜单。

原型：

void IMENUCTL_SetActive(IMenuCtl * pIMenuCtl, boolean bActive)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
bActive | 指定是激活 (TRUE) 还是停用 (FALSE) 菜单控件对象的布尔标记。

返回值：

无

备注：

无

另请参阅：

IMENUCTL_IsActive()

返回函数列表

IMENUCTL_SetColors()

说明：

默认情况下，菜单元素的颜色由设备制造商定义的系统颜色表中的条目确定。 这些条目包括：

CLR_SYS_ITEM | 未选项的背景色。
CLR_SYS_ITEM_TEXT | 未选项和箭头的文本颜色。
CLR_SYS_ITEM_SEL | 已选项的背景色。
CLR_SYS_ITEM_SEL_TEXT | 已选项的文本颜色。
CLR_USER_FRAME | 单边框的颜色。
CLR_SYS_SCROLLBAR | 滚动条边框的颜色。
CLR_SYS_SCROLLBAR_FILL | 滚动条的填充色。
CLR_SYS_TITLE | 标题文本的背景色。
CLR_SYS_TITLE_TEXT | 标题文本的颜色。

此函数允许调用程序覆盖菜单控件对象的大部分这些设置。

原型：

void IMENUCTL_SetColors(IMenuCtl * pIMenuCtl, AEEMenuColors * pc)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pc | 指向包含位掩码（指示需更改颜色的项目）和颜色值的结构的指针。

返回值：

无

备注：

向此函数传递 NULL，将清除菜单颜色。 调用程序无法覆盖三维边框对象的系统设置。

另请参阅：

AEEMenuColors

返回函数列表

IMENUCTL_SetFocus()

说明：

此函数只能用于多选菜单 (MP_MULTI_SEL)。 它可以将焦点设置为指定的菜单项。

原型：

void IMENUCTL_SetFocus(IMenuCtl * pIMenuCtl, uint16 wID);

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针
wID | 要设置的项目 ID。

返回值：

无

备注：

如果给定 (uint16)-1 且在菜单中无法找到，则焦点将转至第一项。

另请参阅：

IMENUCTL_GetFocus()

返回函数列表

IMENUCTL_SetItem()

说明：

此函数用于在创建项目之后设置菜单项中的任何字段，这样可以允许在创建项目后修改项目的图标、文本等。 CtlAddItem 结构中的有效字段由 wFlags 中的位掩码指定。
这些位的定义为：

MSIF_TEXT（更新文本）

MSIF_IMAGE（更新图像）

MSIF_DATA（更新数据）

MSIF_FONT（更新字体）

原型：

boolean IMENUCTL_SetItem
(
IMenuCtl * pIMenuCtl,
uint16 wID,
uint16 wFlags,
CtlAddItem * pai
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
wID | 菜单项 ID。
wFlags | CtlAddItem 结构中的有效字段掩码。
pai | 项目信息结构。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

调用此函数时不会更新设备屏幕。 要显示设备屏幕上的新标题，请使用 IMENUCTL_Redraw()。 软键控件菜单的标题将不会显示。

另请参阅：

CtlAddItem

IMENUCTL_GetItem()

IMENUCTL_Redraw()

返回函数列表

IMENUCTL_SetItemText()

说明：

此函数为给定 ID 的菜单项设置新的文本名称。新文本可通过一个字符串指针，或者一个资源文件名及 ID 传入。如果全都提供，将优先采用字符串指针。

原型：

void IMENUCTL_SetItemText
(
IMenuCtl * pIMenuCtl,
uint16 nItemID,
const char * pszResFile,
uint16 wResID,
AECHAR * pText
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
nItemID | 菜单项标识符。
pszResFile | 以 NULL 结尾包含资源文件名的字符串。
wResID | 资源 ID。
pText | 字符串格式的新菜单项文本。

返回值：

无

备注：

此函数将覆盖当前现有菜单项的菜单名称。 在此例中，nItemID 参数包含当前现有菜单项的 ID。

另请参阅：

无

返回函数列表

IMENUCTL_SetItemTime()

说明：

此函数用于设置日期菜单控件。 它可以设置日程菜单中的项目所关联的开始时间和持续时间。

原型：

void IMENUCTL_SetItemTime
(
IMenuCtl * pIMenuCtl,
uint16 nItemID,
uint16 wMinStart,
uint16 wDuration
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
nItemID | 菜单项标识符。
wMinStart | 起始时间（分钟）。
wDuration | 持续时间（分钟）。

返回值：

无

备注：

无

另请参阅：

IMENUCTL_GetItemTime()

返回函数列表

IMENUCTL_SetProperties()

说明：

此函数用于设置菜单控件特定的属性或标记。 这些属性将定义菜单控件对象的行为。

原型：

void IMENUCTL_SetProperties(IMenuCtl * pIMenuCtl, uint32 dwProps)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
dwProps | 32 位标记或属性组。

以下是为菜单控件对象定义的 32 位属性：

MP_WRAPSCROLL | 如果设置了 MP_WRAPSCROLL，则滚动到屏幕结束时将上卷循环（仅适用于软键和列表控件）。
MP_NO_ARROWS | 如果设置了 MP_NO_ARROWS，即使可以滚动也没有箭头（图标视图）。
MP_NO_REDRAW | 如果设置了 MP_NO_REDRAW，则不在 IMENUCTL_SetActive() 内部或更改选择时调用 IMENUCTL_Redraw()。

以下是仅为菜单控件对象的“图标视图”定义的属性。

MP_ICON_TEXT_TOP
图标视图： 文本位于顶部。
MP_ICON_SINGLE_FRAME
图标视图： 单边框。
MP_UNDERLINE_TITLE
菜单： 标题有下划线。
MP_ICON_DELAY_IMAGE
单帧图像延迟
MP_ICON_ANIMATED
如果设置了 MP_ICON_ANIMATED，则动画选定图标（动画类型或方形图像）。
如果设置了 MP_ICON_ANIMATED 属性，并且图像形状的宽度恰好为高度的倍数，则将根据宽度与高度的倍数把图像分成方块并制成动画。 例如： 如果图像宽为 80 高为 20，且设置了 MP_ICON_ANIMATED 属性，则此图像将被分成
4 帧 20X20 的方形并制成动画。
MP_ICON_NO_CENTERSEL
对于高度只够显示单行图标的图标控件菜单，如果菜单中有多个可以显示的项，则选中的项始终保持居中。 此行为是默认行为，它与菜单中的项目数少于可以显示的项目数时的行为不相同。 该属性将使工具栏行为在以下两种情况中保持一致：
  • 可以显示的项数目 < 菜单项的数目
  • 可以显示的项数目 > 菜单项的数目

以下是仅为菜单控件对象的日程视图定义的两个属性：

MP_CALENDAR
如果设置了 MP_CALENDAR（参见插图），则允许在日程程序中使用标准菜单作为“日期视图”。 在菜单项之间绘制水平线，每项表示特定钟点的日程约会。 <<如果菜单项的左上角出现小方框，则表示下午。 没有方框表示上午。每个菜单项的高度与它的持续时间成正比。>> 使用设备的数字键选择约会钟点，应用程序还可以<<设置>>说明约会的菜单项文本。 <<菜单右边缘的三角形表示当前时间。>>
MP_AUTOSCROLLTIME
如果设置此值，则指定在日程视图中自动滚动。 只有当使用 bActive=TRUE 调用 IMENUCTL_SetActive()，
且菜单当前未激活时，才会出现这种情况。 此后还必须调用 IMENUCTL_Redraw()。

以下是仅为标准菜单或软键控件对象定义的属性：

MP_BI_STATE_IMAGE | 如果设置了该值，没有边框的图像将有两种状态 （未选择或已选择）。
MP_TRI_STATE_IMAGE | 如果设置此值，没有边框的图像将有三种状态 （未选择、已选择或按下）。
MP_MAXSOFTKEYITEMS | 每屏最多可以显示的软键数。

属性只对软键和纯菜单控件有效

MP_MULTI_SEL
如果设置此值，则允许按下多个条目。

返回值：

无

备注：

要重置/清除属性，请设置 dwProps = 0。 例如：

IMENUCTL_SetProperties(pME, 0)

另请参阅：

IMENUCTL_GetProperties()

返回函数列表

IMENUCTL_SetRect()

说明：

此函数用于设置菜单控件对象的控件矩形坐标。 此控件矩形代表在设备屏幕上绘制菜单的区域。 控件矩形值保存在菜单控件对象内。 此函数可以更改控件矩形的值。

原型：

void IMENUCTL_SetRect(IMenuCtl * pIMenuCtl, const AEERect * prc)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
prc | 菜单控件对象的控件矩形。 该矩形指定了在设备屏幕上绘制菜单的 坐标。

返回值：

无

备注：

默认情况下，保存在菜单控件对象中的控件矩形坐标对应于整个设备显示屏幕。 使用 IMENUCTL_SetRect() 可将控件矩形坐标设为新值。 调用此函数后，如果没有其它的菜单绘制操作，则可调用 IMENUCTL_Redraw() 使新的控件矩形坐标生效。

对于软键菜单，默认的控件矩形包含整个设备屏幕，软键菜单则绘制在设备屏幕的底部。 如果使用 IMENUCTL_SetRect() 将控件矩形设为新的区域，如设备屏幕的上半部，则软键菜单将放置在新控件矩形区域的底部，在本例中为屏幕中央。

另请参阅：

AEERect

IMENUCTL_GetRect()

返回函数列表

IMENUCTL_SetSel()

说明：

此函数用于使某个菜单项成为菜单控件对象的当前选择，并在未设置 MP_NO_REDRAW 属性的情况下请求刷新操作。

原型：

void IMENUCTL_SetSel(IMenuCtl * pIMenuCtl, uint16 nItemID)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
nItemID | 将菜单项添加到菜单时使用的菜单项标识符。

返回值：

无

备注：

无

另请参阅：

IMENUCTL_GetSel()

返回函数列表

IMENUCTL_SetSelEx()

说明：

此函数只能用于多选菜单 (MP_MULTI_SEL)。 此函数将根据 bSelected 参数来设置选中项目或取消选中项目。 如果是 TRUE，则将此项目设为选中，如果是 FALSE，则设为取消选中。 要将所有项目设为选中或取消选中状态，请确保所有菜单项的 ID 均非 (uint16)-1，并将 (uint16)-1 作为 wID 参数传入。 菜单中所有项目都将根据 bSelected 参数值进行设置。 如果某项目具有 (uint16)-1 值，则只有该菜单项将根据 bSelected
参数进行设置。

原型：

void IMENUCTL_SetSelEx
(
IMenuCtl * pIMenuCtl,
uint16 wID,
boolean bSelected
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针
wID | 要设置的项目 ID。
bSelected | 选择或取消选择项目。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

IMENUCTL_SetStyle

说明：

此函数用于设置菜单项的显示样式。 正常（未选取）和选取的菜单项可设置不同的样式。 使用该函数还可以更改菜单光标的大小。

原型：

void IMENUCTL_SetStyle
(
IMenuCtl * pIMenuCtl,
AEEItemStyle * pNormal,
AEEItemStyle * pSel
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pNormal | 一般菜单项样式。
pSel | 已选取菜单项的样式。

返回值：

无

备注：

无

另请参阅：

AEEItemStyle

返回函数列表

IMENUCTL_SetTitle()

说明：

此函数用于设置菜单控件对象的标题。 标题使用的文本字符串可以从资源文件或通过 pText 参数指定。

如果 pText 是有效字符串，则该函数将使用此字符串作为标题名称。

如果 pText 为 NULL，则函数将从资源文件中读取对应于给定资源标识符 wResID 的字符串，并将其设为标题名称。

如果文本字符串和资源信息均无效，则函数将会失败。

如果 pText 字段和资源文件信息中的标题字符串均有效，将优先采用 pText 参数字段作为菜单项的标题。

原型：

boolean IMENUCTL_SetTitle
(
IMenuCtl * pIMenuCtl,
const char * pszResFile,
uint16 wResID,
AECHAR * pText
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pszResFile | 以 NULL 结尾，包含资源文件名的字符串。
wResID | 资源标识符。
pText | 以 NULL 结尾，用作菜单标题的字符串。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

调用此函数时不会更新设备屏幕。 要显示设备屏幕上的新标题，请使用 IMENUCTL_Redraw()。

软键控件菜单的标题将不会显示。

另请参阅：

IMENUCTL_Redraw()

返回函数列表

IMENUCTL_Sort()

说明：

此函数用于排列菜单项。 排序类型由调用程序指定，可应用于名称或用户数据排序。 如果未设置MP_NO_REDRAW 菜单标记，该函数可以更新屏幕。

原型：

void IMENUCTL_Sort(IMenuCtl * pIMenuCtl, AEEMenuSortType t)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
t | 排序类型。

返回值：

无

备注：

无

另请参阅：

AEEMenuSortType

IMENUCTL_SortCustom()

返回函数列表

IMENUCTL_SortCustom()

说明：

此函数用于根据用户提供的比较回调排列菜单，这样可以采用简单的名称或值比较以外的其它标准排列菜单。 如果未设置MP_NO_REDRAW 菜单标记，该函数可以更新屏幕。

原型：

void IMENUCTL_SortCustom
(
IMenuCtl * pIMenuCtl,
PFNMENUSORTCOMPARE pfn,
void * pUser
)

参数：

pIMenuCtl | 指向 IMenuCtl 接口对象的指针。
pfn | 用户排序比较回调。
pUser | 指向传递给比较函数的用户上下文的指针。

返回值：

无

备注：

无

另请参阅：

PFNMENUSORTCOMPARE

IMENUCTL_Sort()

返回函数列表


INetMgr 接口

INetMgr 接口函数提供获取和设置设备网络子系统相关参数的机制。它还提供创建多个使用 TCP 或 UDP 在网络上传输和接收数据的 ISocket 接口的方法。 ISocket 接口包含连接套接字、读写连接上的数据以及关闭套接字的函数。

注意： 应用程序必须拥有“网络”或“全部”优先级，才能调用该接口的函数。

INETMGR_OpenSocket() 用于打开 TCP 或 UDP 套接字。 如果成功，该函数返回指向 ISocket 接口实例的指针。 可使用该指针调用 ISOCKET_Connect()，以指定要连接套接字的目标 IP 地址和端口号。 首个套接字连接到设备上后，BREW AEE 将构建网络子系统。 该子系统的组件包括：

  • CDMA 物理层，
  • CDMA 设备的无线链路协议 (RLP)
  • 点到点协议 (PPP) 连接。

连接到设备上的所有套接字将共享这些连接。 通过调用 ISOCKET_Release() 可关闭套接字。 当关闭了设备上连接的最后一个套接字时，BREW AEE 将在指定的延迟时间后终止网络子系统的连接。

INETMGR_GetHostByName() 将主机名（如 brew.qualcomm.com）作为输入并返回可用于访问该主机的 IP 地址列表。 由于获取该列表需要网络通信，因此 INETMGR_GetHostByName() 是异步的。 指定 AEECallback 的输入参数，获得 IP 地址列表后将调用指定函数。INETMGR_GetMyIPAddr() 用于返回设备自身的 IP 地址。INETMGR_NetStatus() 用于返回设备 PPP 连接的当前状态（正在打开、已打开、正在关闭或已关闭）以及网络子系统当前性能的一些统计信息。INETMGR_SetLinger() 用于设置 PPP 连接的延迟时间。 即关闭设备连接的最后一个套接字后，BREW AEE 要等待终止 PPP 连接的时间量（默认值为 30 秒）。

INETMGR_GetLastError() 用于返回由 INetMgr 接口函数检测到的最后一个错误的相关信息。 如果这种函数返回非成功的结果，INETMGR_GetLastError() 将提供详细信息说明函数未能成功执行的原因。

使用 INetMgr 接口的函数

  1. 调用 ISHELL_CreateInstance() 创建 INetMgr 接口的实例。
  2. 根据需要使用 INetMgr 接口的以下函数：
    • 要获取远程或本地 IP 地址信息，请调用 INETMGR_GetHostByName() 或 INETMGR_GetMyIPAddr()。
    • 要获取 PPP 连接状态，请调用 INETMGR_NetStatus()。
    • 要设置 PPP 延迟时间，请调用 INETMGR_SetLinger()。

建立 TCP 或 UDP 套接字并通过它传输数据

  1. 调用 INETMGR_OpenSocket() 打开套接字。
  2. 使用 INETMGR_OpenSocket() 返回的指针调用 ISOCKET_Connect()，将套接字与指定的目标地址连接。
  3. 使用 ISocket 中的函数读写连接上的数据。
  4. 完成必要的数据交换后，调用 ISOCKET_Release() 关闭连接。
  5. 如果不再需要 INetMgr 接口实例，可调用 INETMGR_Release()。

注意： INETMGR_Release() 将使网络子系统无法工作，所以如果设备上还有任何连接着的套接字，就不能释放该接口。

要包含的头文件列表

需要以下头文件：

AEENet.h

函数列表

该接口的函数包括：

INETMGR_AddRef()

INETMGR_GetHostByName()

INETMGR_GetLastError()

INETMGR_GetMyIPAddr()

INETMGR_GetOpt()

INETMGR_NetStatus()

INETMGR_OnEvent()

INETMGR_OpenSocket()

INETMGR_Release()

INETMGR_SetLinger()

INETMGR_SetOpt()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

INETMGR_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

INETMGR_Release()

返回函数列表

INETMGR_GetHostByName()

说明：

此函数用于获取指定主机名所关联的 IP 地址。 结果将放置在结果结构中，并调用回调通知调用程序已完成操作。 AEECallback 记录用于指定和取消回调。

内存 pres 和 pcb 的指针在整个操作过程中（即直到调用完成回调或直到取消操作）
必须保持有效。 调用 INETMGR_Release() 不会自动取消回调。 因此，如果要在完成此操作之前调用此函数，必须先取消指定的回调。 操作前无需初始化结果结构；INETMGR_GetHostByName() 将为其分配值。

AEECallback 必须适当地初始化。 调用 INETMGR_GetHostByName() 后将删除 psz 中的文本字符串。

因为能够保证调用回调，此函数调用始终成功。 与处理请求有关的任何错误都传送给回调函数，以便在其中检查全部的错误。

原型：

void INETMGR_GetHostByName
(
INetMgr * pINetMgr,
AEEDNSResult * pres,
const char * psz,
AEECallback * pcb
)

参数：

pINetMgr | 指向 INetMgr 接口对象的指针。
pres | 指向结果结构的指针。
psz | 要解析的域名，以冒号 (:)、斜线 (/) 或 NULL (\0) 字符结束。
pcb | 指向回调的指针。

返回值：

无

完成时：

  • pres->addrs[] 将包含结果 IP 地址。
  • pres->nResult 将包含获得的地址数目 (1...AEEDNSMAXADDRS)，或者当主机没有地址、请求信息时出错的错误代码。 以下是特定于 INETMGR_GetHostByName() 的错误代码定义：

    • AEE_NET_BADDOMAIN | 主机名残缺；主机名无效。
AEE_NET_UNKDOMAIN | 未知主机，或主机无 IP 地址。
AEE_NET_ETIMEDOUT | 最大时间限度内没有响应。
EUNSUPPORTED | 无需在设备上配置 DNS 服务器便能正常运行， 否则返回 EUNSUPPORTED。
AEE_NET_GENERAL_FAILURE | 分配失败。
AEE_NET_EOPNOTSUPP | 不支持 DNS 查找。

也可能存在与网络连接失败等有关的其它错误代码。 有关完整的列表，请参阅 ISOCKET_SendTo()。

备注：

在 BREW Emulator 中，除非已在 BREW_Emu.dat 的 [Settings] 部分设置 IPAddress 键，否则，该函数将返回 GetHostByName(GetHostName()) 的结果。

另请参阅：

AEEDNSResult

AEECallback

返回函数列表

INETMGR_GetLastError()

说明：

此函数用于返回在 INetMgr 接口中发生的最后一个错误。 返回值取决于最近调用的函数。 每个函数的文档都说明了在其后调用 INETMGR_GetLastError() 将返回什么
结果。

原型：

int INETMGR_GetLastError(INetMgr * pINetMgr)

参数：

pINetMgr
指向用于获取最后错误的 INetMgr 接口对象的指针。

返回值：

最近发生的错误。

备注：

无

另请参阅：

无

返回函数列表

INETMGR_GetMyIPAddr()

说明：

此函数用于返回本地主机或设备的 IP 地址。

原型：

INAddr INETMGR_GetMyIPAddr(INetMgr * pINetMgr)

参数：

pINetMgr
指向用于获取 IP 地址的 INetMgr 接口对象的指针。

返回值：

设备的 IP 地址。

备注：

在 BREW Emulator 中，除非已在 BREW_Emu.dat 的 [Settings] 部分设置 "IPAddress" 键，否则该函数将返回 GetHostByName(GetHostName()) 的结果。

另请参阅：

无

返回函数列表

INETMGR_GetOpt()

说明：

此函数可以提供查询特定网络选项的功能。 在范型上，它与 ISOCKET_IOCtl() 类似，但它处理的是网络级的可配置项目，而不是套接字级的可配置项目。

原型：

int INETMGR_GetOpt
(
INetMgr *pINetMgr,
int nOptName,
void *pOptVal,
int *pnOptSize
);

参数：

pINetMgr | [in] | 指向用于获取 IP 地址的 NetMgr 接口的指针
nOptName | [in] | 标识要获取选项的整数
pOptVal | [out] | 填写特定于选项的数据
pnOptSize | [in/out] | 如果 pOptVal 不为 NULL，则在输入时指定 pOptVal 的大小，该大小必须与选项数据所需大小相匹配。如果 pOptVal 为 NULL，则在输入时将其忽略，在输出时保存选项数据所需大小。

返回值：

如果已获取选项，则返回 SUCCESS。

如果小程序权限禁止访问该选项，则返回 EPRIVLEVEL

如果 nOptName 未知，则返回 EUNSUPPORTED

如果 pOptVal 非空，并且 pOptVal 设置的值小于保存选项数据所需的值，

则返回 EBADPARM

其它错误，具体取决于选项

备注：

以下为当前支持的选项 id：

RLP 选项： 这些选项与设备紧密相关，

由于受到系统权限级别的保护， 因此可能无法配置、使用，或正常工作。

INET_OPT_DEF_RLP3： RLP 默认设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_CUR_RLP3： RLP 当前设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_NEG_RLP3： RLP 协商设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_DNS_SERVERS： 获取系统配置的 DNS 服务器，pOptVal 必须为 INAddr 数组。

INET_OPT_PPP_AUTH： 获取系统配置的 PPP 验证证书（受 PL_SYSTEM 保护）。pOptVal 类型为 char *，返回的字符串格式为："userid\0passwd\0" 。如果传入的缓冲区不够大，则将截断数据，而“不”以空结尾。

副作用：

具体取决于选项

另请参阅：

INETMGR_SetOpt()

返回函数列表

INETMGR_NetStatus()

说明：

此函数用于返回当前网络状态，作为 NetState 类型的 NetState 枚举。 如果 AEENetStats 指针有效，则将使用当前的网络连接信息（例如数据率、活动时间、
已发送字节数和其它项目）填充缓冲区。 调用程序从而能够查看当前会话以及自上次重置设备以来全部会话的性能。

原型：

NetState INETMGR_NetStatus
(
INetMgr * pINetMgr,
AEENetStats * pNetStats
)

参数：

pINetMgr | 指向用于获取当前网络状态的 INetMgr 接口对象的指针。
pNetStats | 指向将填入统计数据的块的指针。

返回值：

指示当前网络状态的 NetState 枚举。

备注：

无

另请参阅：

AEENetStats

NetState

返回函数列表

INETMGR_OnEvent()

说明：

该函数允许调用程序注册接收 INetMgr 操作中的通知。 这些操作包括网络和套接字
函数。

原型：

void INETMGR_OnEvent
(
INetMgr * pINetMgr PFNNETMGREVENT pfn,
void * pUser,
boolean bRegister
)

参数：

pINetMgr | 指向 INetMgr 接口的指针
pfn | 发生事件时要调用的用户指定回调。
pUser | 作为第一参数传给回调的用户指定上下文数据。
bRegister | 如果注册，则为 TRUE；如果撤消注册，则为 FALSE。

返回值：

无

备注：

无

另请参阅：

PFNNETMGREVENT

返回函数列表

INETMGR_OpenSocket()

说明：

该函数用于创建套接字并返回指向 ISocket 接口的指针。

原型：

ISocket * INETMGR_OpenSocket(INetMgr * pINetMgr, NetSocket Type)

参数：

pINetMgr | 指向用于创建套接字的 INetMgr 接口对象的指针。
Type | 指定套接字类型： AEE_SOCK_STREAM 用于 TCP AEE_SOCK_DGRAM 用于 UDP

返回值：

如果成功，则返回指向 ISocket 接口的指针。

如果发生以下错误之一（调用 ISocket 接口 可获取错误代码），则返回 NULL：

AEE_NET_EMFILE，没有更多可打开的套接字。

AEE_NET_ESOCKNOSUPPORT，该地址系列不支持指定的套接字类型。

AEE_NET_GENERAL_FAILURE，一般故障。

备注：

无

另请参阅：

NetSocket

返回函数列表

INETMGR_Release()

说明：

此函数用于减少 INetMgr 接口 对象的引用计数，并在引用计数为 0（零）时进行适当的清理。

原型：

uint32 INETMGR_Release(INetMgr * pINetMgr)

参数：

pINetMgr
指向要减少其引用计数的 INetMgr 接口对象的指针。

返回值：

已减少的对象引用计数。

如果已释放对象，且不再有效，则返回 0（零）。

备注：

如果没有设置延迟时间且 INetMgr 接口对象没有其它打开的套接字，则此函数将关闭相关的 PPP 连接。

另请参阅：

INETMGR_SetLinger()

返回函数列表

INETMGR_SetLinger()

说明：

此函数将 pINetMgr 指定的网络连接的延迟时间设置为 wSecs 指定的值，并返回上一个值。 创建连接时，默认延迟时间设置为 30 秒。

原型：

uint16 INETMGR_SetLinger(INetMgr * pINetMgr, uint16 wSecs)

参数：

pINetMgr | 指向 INetMgr 接口对象的指针。
wSecs | 延迟时间（以秒为单位）。

返回值：

上一个延迟时间值。

备注：

无

另请参阅：

INETMGR_Release()

返回函数列表

INETMGR_SetOpt()

说明：

此函数可以提供配置特定网络选项的功能。 在范型上，它与 ISOCKET_IOCtl() 类似，但它处理的是网络级的可配置项目，而不是套接字级的可配置项目。

原型：

int INETMGR_SetOpt
(
INetMgr *pINetMgr,
int nOptName,
void *pOptVal,
int nOptSize
);

参数：

pINetMgr | 指向用于获取 IP 地址的 INetMgr 接口接口的指针
nOptName | 标识要获取选项的整数
pOptVal | 填写特定于选项的数据
nOptSize | pOptVal 的大小

返回值：

如果已设置选项，则返回 SUCCESS。

如果小程序权限禁止访问该选项，则返回 EPRIVLEVEL

如果 nOptName 未知，则返回 EUNSUPPORTED

如果 nOptSize 设置的大小不符合正确的选项数据，则返回 EBADPARM

其它错误，具体取决于选项

备注：

以下为当前支持的选项 id：

RLP 选项： 这些选项与设备紧密相关，由于受到系统权限级别的保护， 因此可能无法配置、使用，或正常工作。

INET_OPT_DEF_RLP3： RLP 默认设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_CUR_RLP3： RLP 当前设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_NEG_RLP3： RLP 协商设置，pOptVal 必须为 AEERLP3Cfg

INET_OPT_PPP_AUTH： 设置系统配置的 PPP 验证证书（受 PL_SYSTEM 保护）。pOptVal 类型为 char *，输入的字符串格式必须为："userid\0passwd\0"。

副作用：

具体取决于选项

另请参阅：

INETMGR_GetOpt()

返回函数列表


INotifier 接口

通知是一种在其它类发生特定事件时通知类的机制。 例如，小程序可以注册在有 UDP 包进入时获得通知，从而能够接收 EVT_NOTIFY 事件。

通知程序是在发生特定事件时生成并分发通知的类。 例如，INetMgr 接口可以充当通知程序，并在网络连接打开或关闭时发送通知。 每当通知程序需要发送通知时，都要使用 ISHELL_Notify()。

小程序可以使用 ISHELL_RegisterNotify() 进行注册，以获得通知。 例如，小程序可以注册以接收 INetMgr 接口类特定事件的通知。

INotifier 接口提供了需要发送被其它小程序接收的通知的任何类都必须实现的函数。

您可以定义该类能够发出的通知（掩码）组。 例如，INetMgr 接口类可以发出的通知包括 NMASK_OPENED、NMASK_CLOSED 和 NMASK_UDP_LISTEN。 这些掩码必须对其它小程序可用，以便关注这些通知的小程序可以注册获取它们。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

该接口的函数包括：

INOTIFIER_AddRef()

INOTIFIER_Release()

INOTIFIER_SetMask()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

INOTIFIER_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

INOTIFIER_Release()

返回函数列表

INOTIFIER_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

INOTIFIER_AddRef()

返回函数列表

INOTIFIER_SetMask()

说明：

AEE 外壳可以调用此函数，告知通知程序类其它小程序所关注的全部已发通知。
实现 INotifier 接口的所有通知程序类都必须实现该函数。

该函数仅限于 AEE 外壳内部调用， 其它小程序或类不能直接调用它。

原型：

void INOTIFIER_SetMask(INotifier * pINotifier, const uint32 * dwMasks)

参数：

pINotifier | 指向 INotifier 接口对象的指针。
dwMasks | 表示其它小程序所关注的通知的掩码数组。

返回值：

无

备注：

一个类可以发出多个通知，例如 NMASK_OPENED、NMASK_CLOSED 和 NMASK_UDP_LISTEN。 但是，注册接收通知的小程序也许只关注 NMASK_OPENED 和 NMASK_CLOSED 通知。 每当小程序使用 ISHELL_RegisterNotify() 注册 接收通知时，它必须指定它所关注的通知的掩码。
然后，AEE 外壳调用 INOTIFIER_SetMask()，告知通知程序该小程序所关注的全部通知。

另请参阅：

ISHELL_RegisterNotify()

ISHELL_Notify()

返回函数列表


IPeek 接口

Peek 接口是一个抽象的数据源，它提供的取数/推进功能可用于在 IPeek 接口对象的缓冲区中积累数据。 只要调用程序不试图修改 IPeek 函数中的取数数据（如果它是通过使用 const 数据创建的 ISOURCEUTIL_PeekFromMemory() 接收的数据），就可以对数据进行检查甚至修改，直至用尽数据。

要包含的头文件列表

需要以下头文件：

AEESource.h

函数列表

此接口的函数包括：

IPEEK_AddRef()

IPEEK_Advance()

IPEEK_Exhausted()

IPEEK_Peek()

IPEEK_Peekable()

IPEEK_QueryInterface()

IPEEK_Read()

IPEEK_Readable()

IPEEK_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IPEEK_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IPEEK_Release()

返回函数列表

IPEEK_Advance()

说明：

此函数可以使取数指针在缓冲区中前进或后退。

原型：

void IPEEK_Advance(IPeek * pIPeek, int cbAdvance)

参数：

pIPeek | 指向 IPeek 接口对象的指针。
cbAdvance | 要前进（或后退，如果值为负）的字节数。

返回值：

无

备注：

字节数大于已缓冲的字符数将使指针前进至所有缓冲字符的末端。

另请参阅：

无

返回函数列表

IPEEK_Exhausted()

说明：

此函数据用于确定 ISource、IPeek 或 IGetLine 是否用尽数据。

定义：

IPEEK_Exhausted(code)((unsigned) - (code) < 2U)

参数：

code
从 Read()、Peek() 或 GetLine() 返回的值

返回值：

如果源数据已用尽（无更多数据），则返回 TRUE。

否则，返回 FALSE。

备注：

如果是 Peek() 和 GetLine()，可能仍然存在返回的数据。 请检查 _Peek() 的 cbAvailable 参数或 GetLine 数据结构的 nLen 字段。

另请参阅：

无

返回函数列表

IPEEK_Peek()

说明：

此函数用于返回指向缓冲数据的指针，并可随意尝试将更多的数据读入缓冲区。

原型：

char * IPEEK_Peek
(
IPeek * pIPeek,
int cbWanted,
int * pcbAvailable,
int * pnCode
)

参数：

pIPeek | [in] | 指向 IPeek 接口对象的指针。
cbWanted | [in] | 指定的字节数。 如果缓冲区中已存在该数量的字节， 则 Peek() 将不执行额外操作，否则它将尝试从网络或其它数据源复制更多的数据。 传递 0（零）可快速查询当前缓冲区状态。 IPEEK_PEEKMAX 定义为表示“尽可能多地返回”。
pcbAvailable | [out] | 缓冲数据的大小。
pnCode | [out] | 说明返回值以外的数据的可用性：
 |  | IPEEK_END | 无更多数据（数据流中遇到 END）。
 |  | IPEEK_ERROR | 无更多数据（数据流中遇到 ERROR）。
 |  | IPEEK_FULL | 数据受缓冲区大小限制，要获取新数据就必须忽略已缓冲的数据。
 |  | IPEEK_WAIT | 等待 IPEEK_Peekable()，以再次调 用；轮询数据源，当前无可用数据。
 |  | IPEEK_UNK | 请求量小于缓冲量；请使用更大的 cbWanted 再次调用；不轮询数据源。

返回值：

缓冲数据的起始位置。

备注：

无

另请参阅：

无

返回函数列表

IPEEK_Peekable()

说明：

当有更多的未缓冲数据可用时，可以使用此函数调用回调。 调用回调之后，IPEEK_Peek() 可以返回比以前更多的数据。

原型：

void IPEEK_Peekable(IPeek * pIPeek, AEECallback * pcb)

参数：

pIPeek | 指向 IPeek 接口对象的指针。
pcb | 在 ISource 可读时，指向调用位置的指针。

返回值：

无

备注：

现有的缓冲数据不会引起立即回调。 请确保仅在确定当前缓冲数据不足以继续进行后，才调用此函数。

另请参阅：

无

返回函数列表

IPEEK_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IPEEK_QueryInterface(IPeek * pIPeek, AEECLSID idReq, void * * ppo)

参数：

pIPeek | [in] | 指向 IPeek 接口对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [out] | 返回的对象。 由此函数填充。

返回值：

如果已找到接口，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT。

备注：

*ppo 中的指针将被设为指向新接口（引用计数为正），如果对象不支持该 ClassID，

则为 NULL。

另请参阅：

AEECLSID 列表

返回函数列表

IPEEK_Read()

说明：

此函数用于将源数据流中的字节复制到指定缓冲区。 复制的所有字节均“用尽”（即，“读指针”前置）。

原型：

int IPEEK_Read(IPeek * pIPeek, char * pc, int cb)

参数：

pIPeek | 指向 IPeek 接口对象的指针。
pc | 指向接收所读字节的缓冲区的指针。
cb | pc 的大小。

返回值：

如果成功，则返回读取的字节数。

否则，返回错误代码。

ISOURCE_END，对等端正常切断连接（无更多数据）。

ISOURCE_ERROR，遇到错误（无更多数据）。

ISOURCE_WAIT，此时无可用数据；调用 Readable() 以等待。

备注：

ISOURCE_WAIT 返回值用于取代错误返回值和 EWOULDBLOCK 错误代码。

另请参阅：

无

返回函数列表

IPEEK_Readable()

说明：

此函数用于在 IPEEK_Read() 返回非 IPEEK_WAIT 的其它值时，调度或取消要调用的回调。

原型：

void IPEEK_Readable(IPeek * pIPeek, PFNNOTIFY pfn, void * pvUwer)

参数：

pIPeek | 指向 IPeek 接口对象的指针。
pfn | 指向回调函数的指针。
pvUser | 定义回调。 向这两个参数传递 NULL 会取消先前调度的回调。

返回值：

无

备注：

ISOURCE_WAIT 返回值用于取代错误返回值和 EWOULDBLOCK 错误代码。

另请参阅：

PFNNOTIFY

返回函数列表

IPEEK_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IPEEK_AddRef()

返回函数列表


IPosDet 接口

此接口提供使用扇区信息或 GPS 信息进行的定位服务。 要使用基于扇区的定位方法
（例如 IPOSDET_GetSectorInfo()），需要扇区信息权限。 类似地，基于 GPS 的定位方法（例如 IPOSDET_SetGPSConfig()、IPOSDET_GetGPSConfig() 和IPOSDET_GetGPSInfo()），也需要定位权限。

IPOSDET_GetGPSInfo() 是一种使用 AEECallback 的异步方法。 必须注意确保以传址方式传递给这些方法的回调和信息结构在作用域以内，直至回调返回。 此外，如果在回调返回之前就进行多个扇区信息或 GPS 信息请求，则接口行为将不可预测。

BREW SDK 用户可以在“工具->GPS 模拟”菜单中设置 GPS 模拟，以使用预录制的 NMEA 文件作为 GPS 输入，或连接可输出 NMEA 的 GPS 设备。 脱机实用程序 NMEALogger.exe 可用于记录 NMEA 文件，其中的数据来自连接至台式/便携式计算机串行端口的 GPS 设备。
该 NMEA 文件可在以后用作 GPS 输入。 有关详细信息，请参阅SDK 用户指南 和SDK 实用程序指南。

要包含的头文件列表

需要以下头文件：

AEEPosDet.h

函数列表

此接口的函数包括：

IPOSDET_AddRef()

IPOSDET_GetGPSConfig()

IPOSDET_GetGPSInfo()

IPOSDET_GetSectorInfo()

IPOSDET_QueryInterface()

IPOSDET_Release()

IPOSDET_SetGPSConfig()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IPOSDET_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IPOSDET_Release()

返回函数列表

IPOSDET_GetGPSConfig()

说明：

此函数用于获取 GPS 引擎当前的 GPS 配置。

原型：

int IPOSDET_GetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig);

参数：

pIPosDet | [in] | 指向 IPosDet 接口对象的指针。
pConfig | [out] | 指向 GPS 配置的指针。 有关详细信息，请参阅 AEEGPSConfig。

返回值：

如果此函数成功，则返回 SUCCESS。

否则，返回错误代码。

EPRIVLEVEL，如果调用程序没有调用该函数所需的 PL_POS_LOCATION
优先级。

EBADPARM，如果 pConfig 为 NULL

EUNSUPPORTED，如果不支持此函数。

备注：

除非已调用此函数，否则首次调用 IPOSDET_GetGPSInfo() 时，GPS 引擎配置使用的将是默认设置。 只有紧随 IPOSDET_SetGPSConfig() 调用之后的定位请求才能使用新配置。挂起响应回调的 IPOSDET_GetGPSInfo() 请求不受该方法的影响。

另请参阅：

AEEGPSConfig

IPOSDET_SetGPSConfig()

返回函数列表

IPOSDET_GetGPSInfo()

说明：

此函数用于返回 GPS 定位信息。 它将返回纬度、经度、海拔高度以及向量信息，
如水平和垂直速度、方向及水平信息的误差。 该函数为异步调用，完成时将调用
pcb 指定的回调函数。

原型：

int IPOSDET_GetGPSInfo
(
IPosDet *pIPosDet,
AEEGPSReq req,
AEEGPSAccuracy accuracy,
AEEGPSInfo *pGPSInfo,
AEECallback *pcb,
)

参数：

pIPosDet
[in]
指向 IPosDet 接口对象的指针。
req
[in]
请求类型：
  • AEEGPS_GETINFO_LOCATION、AEEGPS_GETINFO_VELOCITY、AEEGPS_GETINFO_ALTITUDE。
以上标记可以组合使用以获取多种信息。
accuracy
[in]
为请求选定的精确度级别。
pGPSInfo
[out]
输入时，该参数必须是指向 AEEGPSInfo 结构的有效指针。 返回时，此结构的成员包含 GPS 信息。 调用程序必须确保此结构有效，直到调用 pcb 指定的回调。
pcb
[in]
完成定位后调用的回调函数。

返回值：

如果此函数成功，则返回 SUCCESS。

如果调用程序没有足够的优先级 (PL_POS_LOCATION) 调用此函数，则返回 EPRIVLEVEL

如果 pGPSInfo 或 pcb 为 NULL，则返回 EBADPARM

如果不支持此函数，则返回 EUNSUPPORTED。

如果是常规失败，则返回 EFAILED

备注：

无

另请参阅：

AEEGPSInfo

返回函数列表

IPOSDET_GetSectorInfo()

说明：

此函数用于返回扇区定位信息，例如 SystemID、NetworkID、BaseStationID、BaseStationClass 和最佳导频信号。 要调用此函数，调用程序（应用程序）必须具有 PL_SECTORINFO 优先级。 如果没有此优先级，调用该函数将失败。

原型：

int IPOSDET_GetSectorInfo
(
IPosDet * pIPosDet,
AEESectorInfo * pSecInfo
)

参数：

pIPosDet | [in] | 指向 IPosDet 接口指针的指针。
pSecInfo | [out] | 该参数必须是指向 AEESectorInfo 结构的值指针。 返回时，此结构的成员将包含扇区信息。

返回值：

如果函数成功，则返回 AEE_SUCCESS。

否则，将返回错误代码。

EPRIVLEVEL，如果调用程序没有足够的优先级 (PL_SECTORINFO)
来调用此函数。

EUNSUPPORTED，如果不支持此函数。

EFAILED，如果是常规失败。

备注：

无

另请参阅：

AEESectorInfo

返回函数列表

IPOSDET_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IPOSDET_QueryInterface
(
IPosDet * pIPosDet,
AEECLSID idReq,
void * * ppo
)

参数：

pIPosDet | [in] | 指向 IPosDet 接口对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [out] | 返回的对象。 由此函数填充。

返回值：

如果已找到接口，则返回 SUCCESS。

否则，将返回错误代码。

ENOMEMORY，内存不足。

ECLASSNOTSUPPORT，不支持请求的接口。

备注：

*ppo 中的指针将被设为指向新接口（引用计数为正），如果对象不支持该 ClassID，则为 NULL。

另请参阅：

无

返回函数列表

IPOSDET_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IPOSDET_AddRef()

返回函数列表

IPOSDET_SetGPSConfig()

说明：

此函数用于设置 GPS 引擎将要使用的 GPS 配置。

原型：

int IPOSDET_SetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig);

参数：

pIPosDet | 指向 IPosDet 接口对象的指针。
pConfig | 指向 GPS 配置的指针。 有关详细信息，请参阅 AEEGPSConfig。

返回值：

如果此函数成功，则返回 SUCCESS。

否则，将返回错误代码。

EPRIVLEVEL，如果调用程序没有足够的优先级

(PL_POS_LOCATION) 来调用此函数

EBADPARM，如果 pConfig 为 NULL

EUNSUPPORTED，如果不支持此函数。

备注：

除非已调用此函数，否则首次调用 IPOSDET_GetGPSInfo() 时，GPS 引擎配置使用的将是默认设置。 只有紧随 IPOSDET_SetGPSConfig() 调用之后的定位请求才能使用新配置。挂起响应回调的 IPOSDET_GetGPSInfo() 请求不受该方法的影响。

另请参阅：

AEEGPSConfig

IPOSDET_GetGPSConfig()

返回函数列表


IQueryInterface

IQueryInterface (IQI) 是派生可扩展 API 对象类的底层对象类。 它提供的标准机制可在维护二进制兼容性的同时实现对象的可扩展功能。

要包含的头文件列表

需要以下头文件：

AEE.h

函数列表

此接口的函数包括：

IQI_AddRef()

IQI_QueryInterface()

IQI_Release()

IQI_SELF()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IQI_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IQI_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IQI_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IQI_QueryInterface
(
IQueryInterface * pIQueryInterface,
AEECLSID idReq,
void * * ppo
)

参数：

pIQueryInterface | [in] | 指向 IQueryInterface对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [in/out] | 返回的对象。 由此函数填充。

返回值：

如果已找到接口，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT。

备注：

  • 如果 *ppo 为接口指针，则 *ppo 中的指针将被设置为新接口（同时增加引用计数），如果对象不支持 ClassID，则将被设置为 NULL。

您可以将 IQI_SELF() 宏用作仅实现一个接口的任何 QueryInterface 子函数中的 QueryInterface() 方法体。 使用此宏：

int ISomething_QueryInterface(ISomething * me, AEECLSID idReq, void * * ppo)
{
if (NULL != ( * ppo = IQI_SELF(me,idReq,ppo,AEECLSID_SOMETHING)))
{
IQI_AddRef( * ppo);
return SUCCESS;
} else
{
return ECLASSNOTSUPPORT;
}
}
  • 如果 *ppo 为数据结构指针，则 *ppo 将设置为 classID 所代表的内部数据，如果对象不支持 classID，则设置为 NULL。

另请参阅：

无

返回函数列表

IQI_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

IQI_AddRef()

BREW SDKTM AEE 分层结构图表.

返回函数列表

IQI_SELF()

说明：

此帮助宏用于使用单个接口实现的对象。

原型：

IQI_SELF (p,idReq,pp,idImp)
(*(pp)=((((idReq)==(idImp))||((idReq)==AEECLSID_ QUERYINTERFACE))?(p):0))

参数：

p | 对象。
idReq | 传递到 QueryInterface 的 clsid，即请求的 clsid。
pp | 输出接口指针。
idImp | 对象所实现的接口的（IQueryInterface 除外）clsid。

返回值：

\

如果对象是 idReq 或 idImpl，则返回 p。

备注：

使用 IQI_SELF：

int ISomething_QueryInterface(ISomething * me, AEECLSID idReq, void * * ppo)
{if (NULL != IQI_SELF(me,idReq,ppo,AEECLSID_SOMETHING))
{IQIBASE_AddRef( * ppo);
return SUCCESS;
} else
{return ECLASSNOTSUPPORT;
}
}

副作用：

ppo 参数被设置为 p 或 NULL。

另请参阅：

无

返回函数列表


IRamCache 接口

IRamCache 接口利用 TTL 提供有限大小和有限项目的 LRU 缓存，并用堆上存储其中的记录。 IRamCache 的 BREW 实现为单链表。 记录则由“名称－值”对构成，其中每个“名称－值”对均可为一个二进制 blob。 关键字和值都是要包含的头文件列表

需要以下头文件：

AEERamCache.h

函数列表

此接口的函数包括：

IRAMCACHE_Add()

IRAMCACHE_Find()

IRAMCACHE_FlushAll()

IRAMCACHE_FlushExpired()

IRAMCACHE_Remove()

IRAMCACHE_SetTTL()

IRAMCACHE_SetMaxSize()

IRAMCACHE_SetMaxEntries()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IRAMCACHE_Add()

说明：

此函数用于将记录添加至缓存。

原型：

int IRAMCACHE_Add
(
IRamCache *pIRamCache,
const char *pKey,
int nKeyLen,
const char *pVal,
int nValLen);

参数：

pIRamCache | 指向 IRamCache 接口对象的指针
pKey | 关键字数据
nKeyLen | 关键字数据的长度
pVal | 值数据
nValLen | 值数据的长度

返回值：

如果已将记录添加至缓存，则返回 SUCCESS

如果添加违反了缓存约束

（超出最大大小或最大条目数为 0），则返回 EFAILED

如果无法创建要添加的记录，则返回 ENOMEMORY

备注：

IRamCache 将复制 pKey 和 pVal 的内容，调用后可以将这些内容丢弃。

副作用：

过期记录将被清除添加的记录位于 LRU 列表首位。

另请参阅：

无

返回函数列表。

IRAMCACHE_Find()

说明：

此函数用于在缓存中查找记录。

原型：

int IRAMCACHE_Find
(
IRamCache *pIRamCache,
const char *pKey,
int nKeyLen,
char *pVal,
int *pnValLen)

参数：

pIRamCache | [in] | 指向 IRamCache 接口对象的指针。
nKeyLen | [in] | 关键字数据的长度。
pVal | [out] | 值数据。
pnValLen | [in/ out] | pVal 的大小（如果 pVal 为 NULL）pnValLen 在输入时将被忽略，而输出时则保存缓存中数据的大小（如果有）

返回值：

如果找到记录，则返回 SUCCESS

如果缓存中没有该记录，则返回 EFAILED

备注：

无

副作用：

过期记录将被清除

另请参阅：

无

返回函数列表。

IRAMCACHE_FlushAll()

说明：

此函数用于清空缓存，将所有记录删除

原型：

int IRAMCACHE_FlushAll(IRamCache *pIRamCache);

参数：

pIRamCache
指向 IRamCache 接口对象的指针

返回值：

SUCCESS

备注：

无

另请参阅：

无

返回函数列表。

IRAMCACHE_FlushExpired()

说明：

此函数用于执行缓存截止，将所有过期记录删除

原型：

int IRAMCACHE_FlushExpired(IRamCache *pIRamCache);

参数：

pIRamCache
指向 IRamCache 接口对象的指针

返回值：

SUCCESS

备注：

无

另请参阅：

无

返回函数列表。

IRAMCACHE_Remove()

说明：

此函数用于从缓存中删除记录

原型：

int IRAMCACHE_Remove
(
IRamCache *pIRamCache,
const char *pKey,
int nKeyLen
);

参数：

pIRamCache | 指向 IRamCache 接口对象的指针
pKey | 关键字数据
nKeyLen | 关键字数据的长度

返回值：

如果找到记录并将其删除，则返回 SUCCESS

如果缓存中没有该记录，则返回 EFAILED

备注：

无

副作用：

过期记录将被清除。

另请参阅：

无。

返回函数列表。

IRAMCACHE_SetMaxEntries()

说明：

此函数用于设置缓存中容许的最大条目数。

原型：

int IRAMCACHE_SetMaxEntries(IRamCache *pIRamCache, int nNum);

参数：

pIRamCache | 指向 IRamCache 接口对象的指针
nNum | 新的条目限制

返回值：

原来的条目限制

备注：

无

副作用：

缓存调整为新约束，并将 LRU 条目和过期条目从缓存中删除

另请参阅：

无

返回函数列表。

IRAMCACHE_SetMaxSize()

说明：

此函数可设置用来保存关键字和值的 RamCache 的最大大小（以字节为单位）

原型：

int IRAMCACHE_SetMaxSize(IRamCache *pIRamCache, int nSize);

参数：

pIRamCache | 指向 IRamCache 接口对象的指针
nSize | 新的大小（以字节为单位）

返回值：

原来的最大大小。

备注：

此数字不包括存储关键字和值的开销，它仅限于已计数的关键字和值的字节

副作用：

缓存调整为新约束，并将 LRU 条目和过期条目从缓存中删除

另请参阅：

无

返回函数列表。

IRAMCACHE_SetTTL()

说明：

此函数用于设置缓存中记录的 TTL（以毫秒为单位），仅应用于后续添加的记录。

原型：

uint32 IRAMCACHE_SetTTL(IRamCache *pIRamCache, uint32 ulTTL)

参数：

pIRamCache | 指向 IRamCache 接口对象的指针
ulTTL | 新的 TTL（以毫秒为单位）

返回值：

原来的 TTL 值

备注：

无

另请参阅：

无

返回函数列表。


IRSA 接口

该接口可使 BREW 开发者使用 RSA (Rivest-Shamir-Adleman) 算法对数据进行加密或签名。 此算法是一种用于公共密钥密码系统的非对称块加密方式，它允许加密和数字签名。
RSA 算法用于 Internet 标准，如 S/MIME、IPSec 和 SSL/TLS。 RSA 运算实质上是模数求幂，其中的计算由一系列模数相乘来实现。 RSA 系统的安全性基于大质数乘积难以因式分解的假设。

IRSA 的实例可以使用 ISHELL_CreateInstance() 创建，该函数将 AEECLSID_RSA
（32 位 ClassID）作为输入参数之一。 如果 ISHELL_CreateInstance() 成功，则返回 IRSA 接口指针。 该接口指针用于调用 IRSA 函数。 调用 IRSA_Init() 可设置构成密钥的模数和指数。 初始化密钥后，调用 IRSA_RSA() 对数据进行加密或解密。 完成 IRSA 之后，调用 IRSA_Release()。

要包含的头文件列表

需要以下头文件：

AEESecurity.h

函数列表

该接口的函数包括：

IRSA_AddRef()

IRSA_Decrypt()

IRSA_Encrypt()

IRSA_Init()

IRSA_ModExp

IRSA_Release()

IRSA_RSA()

IRSA_VerifySig()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IRSA_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IRSA_Release()

返回函数列表

IRSA_Decrypt()

说明：

此函数用于解密数据。 此例程使用 IRSA 对象中指定的指数和模数对数据进行解密，并根据填充类型参数删除填充，然后将原始数据返回给用户。

原型：

void IRSA_Decrypt
(
IRSA* pIRSA,
const byte* pbIn,
int cbIn,
byte* pbOut,
int *pcbOut,
int ePadType,
uint32* pdwResult,
AEECallback *pCB
)

参数：

pIRSA | 指向 IRSA 接口的指针
pbIn | 指向要解密的数据缓冲区的指针
cbIn | 输入缓冲区的长度
pbOut | 指向存储加密数据的缓冲区的指针（调用程序已分配）
pcbOut | 输入时指定输出缓冲区长度；输出时指定数据长度
ePadType | 使用的填充类型
pdwResult | 结果代码
pCB | 完成回调

返回：

无。 结果代码通过 pdwResult 参数返回。

SUCCESS

AEE_CRYPT_KEY_INVALID_KEY -密钥出现问题

ENOMEMORY -处理时内存不足

SIG_BN_ERROR -密钥或内存出错

AEE_CRYPT_BUFFER_TOO_SMALL -输出缓冲区太小

AEE_CRYPT_INVALID_PADTYPE -给出的填充类型有误

AEE_CRYPT_ROLLBACKATTACK -正在解码 SSL 填充

其它一些填充错误

备注：

此例程根据调用程序事先配置 IRSA 对象的方式以及用户指定的填充类型，进行私有或公开解密。

另请参阅：

无

返回函数列表

IRSA_Encrypt()

说明：

此函数用于加密数据。 此例程使用不超过 IRSA 对象中指定的模数大小的数据量，
并以 ePadType 参数指定的填充类型对其进行填充，然后使用用户在上一次调用中建立 IRSA 对象所用模数和指数进行加密。

原型：

void IRSA_Encrypt
(
IRSA* pIRSA,
const byte* pbIn,
int cbIn,
byte* pbOut,
int *pcbOut,
int ePadType,
uint32* pdwResult,
AEECallback *pCB
)

参数：

pIRSA | 指向 IRSA 接口的指针
pbIn | 指向要加密的数据缓冲区的指针
cbIn | 输入缓冲区的长度
pbOut | 指向存储加密数据的缓冲区的指针（调用程序已分配）
pcbOut | 输入时指定输出缓冲区的长度；输出时指定数据长度
ePadType | 使用的填充类型
pdwResult | 结果代码
pCB | 完成回调

返回：

无。 结果代码将在 pdwResult 参数中传回。

SUCCESS

AEE_CRYPT_KEY_INVALID_KEY -密钥出现问题

ENOMEMORY -处理时内存不足

SIG_BN_ERROR -密钥或内存出错

AEE_CRYPT_BUFFER_TOO_SMALL -输出缓冲区太小

AEE_CRYPT_INVALID_PADTYPE -给出的填充类型有误

其它一些填充错误

备注：

此例程根据调用程序事先配置 IRSA 对象的方式以及用户指定的填充类型，进行私有或公开加密。

另请参阅：

无

返回函数列表

IRSA_Init()

说明：

此函数用于使用 RSA 初始化加密或解密密钥。 RSA 实验室建议公司使用 128 字节（1024 位）大小的密钥。 BREW API 不限制密钥大小。 模数越大，安全性越高，但会降低 RSA 算法的运算速度。 通常选择较小的公用指数和较大的私有指数， 这使得加密快于解密，验证快于签名。 调用 IRSA_RSA() 之前请先调用此函数。

原型：

int IRSA_Init
(
IRSA* pIRSA,
const byte* pchModulus,
int cbModulus,
const byte* pchExponent,
int cbExponent
)

参数：

pIRSA |  | 指向 IRSA 接口对象的指针。
pchModulus | [in] | 指向模数的指针。
cbModulus | [in] | 模数大小（以字节为单位）。
pchExponent | [in] | 指向公开或私有指数的指针。
chExponent | [in] | 公开或私有指数的大小（以字节为单位）。

返回值：

如果 RSA 密钥初始化成功，则返回 SUCCESS。

如果密钥无效，则返回 AEE_CRYPT_INVALID_KEY

如果所有可用内存均被占用，则返回 ENOMEMORY。

备注：

无

另请参阅：

无

返回函数列表

IRSA_ModExp

说明：

此函数用于执行基本的模数求幂，是 RSA 算法的基本运算。 它是 IRSA_RSA() 的无阻塞替换。

原型：

void IRSA_ModExp(

IRSA *pIRSA,
const byte* pbIn,
int cbIn,
byte** ppbOut,
int* pcbOut,
uint32 *pdwResult,
AEECallback *pCB

参数：

pIRSA | 指向要操作的 IRSA 对象的指针
pbIn | 指向输入缓冲区的指针
cbIn | 输入数据的长度
ppbOut | 指向结果的指针
pcbOut | 结果数据的长度
pdwResult | 运算结果的存储空间
pCB | 用户定义的在完成时调用的回调

返回：

返回值在 pdwResult 指向的 uint32 中返回。

SUCCESS

AEE_CRYPT_KEY_INVALID_KEY - 密钥出现问题

ENOMEMORY -处理时内存不足

SIG_BN_ERROR -密钥或内存出错

备注：

无

另请参阅：

无

返回函数列表

IRSA_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IRSA_AddRef()

返回函数列表

IRSA_RSA()

说明：

此函数用于使用 RSA 进行加密或解密。 每次调用 RSA() 均会加密块大小的模数。
要对大于模数的数据加密，必须将其分成多个块。 使用多个 RSA 运算加密数据的另一个方法是，先使用诸如 MD5 或 SHA1 的算法散列数据，然后再使用一个 RSA 运算加密结果。 此函数分配输出缓冲区，并在调用 IRSA_Release() 时释放该缓冲区。

原型：

int IRSA_RSA
(
IRSA* pIRSA,
const byte *pchIn,
int cbIn,
byte **pchOut,
int* pcbOut,
int reserved
)

参数：

pIRSA |  | 指向 IRSA 接口对象的指针。
pchIn | [in] | 指向要加密（或解密）的数据的指针。
cbInavailable | [in] | 输入数据大小（以字节为单位）。
pchOut | [out] | 接收加密（或解密）数据的缓冲区。
pcbOut | [out] | 保留的输出大小（以字节为单位） - 应为 0（零）。

返回值：

如果发生加密或解密，则返回 SUCCESS。

如果加密（或解密）密钥无效，则返回 AEE_CRYPT_INVALID_KEY。

如果加密（或解密）失败，则返回 EFAILED。

备注：

输出缓冲区由 BREW AEE 分配。

另请参阅：

无

返回函数列表

IRSA_VerifySig()

说明：

此函数用于验证签名。 此例程使用签名和摘要，并验证签名是否有效。 它对签名进行解密，将解码任何基本签名格式（如 PKCS1）的填充删除，然后比较摘要。

原型：

void IRSA_VerifySig
(
IRSA *pIRSA,
const byte* pbSig,
int cbSigLen,
const byte* pbDigest,
int cbDigestLen,
int eSigType,
uint32* pdwResult,
AEECallback *pCB
)

参数：

pIRSA | 指向 RSA 对象的指针
pbSig | 指向包含签名的缓冲区的指针
cbSigLen | 签名的长度
pbDigest | 指向包含摘要的缓冲区的指针
cbDigestLen | 摘要的长度
eSigType | AEE_RSA_SIG_ 之一
pdwResult | 结果代码
pCB | 指向用户定义的回调例程的指针

返回：

无。 结果代码置于 pdwResult 参数中。

SUCCESS

AEE_CRYPT_KEY_INVALID_KEY -密钥出现问题

ENOMEMORY -处理时内存不足

SIG_BN_ERROR -密钥或内存出错

AEE_CRYPT_BUFFER_TOO_SMALL -输出缓冲区太小

AEE_CRYPT_INVALID_PADTYPE -给出的填充类型有误

AEE_CRYPT_ROLLBACKATTACK -正在解码 SSL 填充

SIG_INVALID -签名验证失败

其它一些填充错误

备注：

无

另请参阅：

无

返回函数列表


IRingerMgr 接口

IRingerMgr 接口提供 BREW 接口来管理设备上的振铃器。 以 AEECLSID_RINGER 为参数调用 ISHELL_CreateInstance() 即可获取此接口。 该类使调用程序可以执行以下功能：

  • 获取支持格式的列表
  • 获取振铃器类别的列表
  • 获取某类别振铃器的列表
  • 播放振铃器
  • 删除振铃器
  • 设置振铃器类别或默认值

要包含的头文件列表

需要以下头文件：

AEERinger.h

函数列表

此接口的函数包括：

IRINGERMGR_AddRef()

IRINGERMGR_Create()

IRINGERMGR_EnumCategoryInit()

IRINGERMGR_EnumNextCategory()

IRINGERMGR_EnumNextRinger()

IRINGERMGR_EnumRingerInit()

IRINGERMGR_GetFormats()

IRINGERMGR_GetNumberFormats()

IRINGERMGR_GetRingerID()

IRINGERMGR_GetRingerInfo()

IRINGERMGR_RegisterNotify()

IRINGERMGR_Remove()

IRINGERMGR_SetRinger()

IRINGERMGR_Stop()

IRINGERMGR_Play()

IRINGERMGR_PlayEx()

IRINGERMGR_PlayFile()

IRINGERMGR_PlayStream()

IRINGERMGR_RegisterNotify()

IRINGERMGR_Release()

IRINGERMGR_Remove()

IRINGERMGR_SetRinger()

IRINGERMGR_Stop()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IRINGERMGR_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IRINGERMGR_Release()

返回函数列表

IRINGERMGR_Create()

说明：

此函数用于创建新振铃器。

原型：

int IRINGERMGR_Create
(
IRingerMgr * pIRingerMgr,
const AECHAR * pszName,
AEESoundPlayerFile format,
IAStream * ps
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pszName | 振铃器名称。
format | 振铃器格式。
ps | 振铃器数据流。

返回值：

如果正在创建振铃器，则返回 SUCCESS。

其它错误代码。

EFAILED，振铃器无效。

备注：

无

另请参阅：

AEESoundPlayerFile

返回函数列表

IRINGERMGR_EnumCategoryInit()

说明：

此函数用于在枚举类别时初始化枚举上下文。

原型：

int IRINGERMGR_EnumCategoryInit(IRingerMgr * pIRingerMgr)

参数：

pIRingerMgr
指向 IRingerMgr 接口对象的指针。

返回值：

如果已初始化枚举，则返回 SUCCESS。

其它特定于实现的错误代码。

备注：

此函数可重复调用。 请在调用 IRINGERMGR_EnumNextCategory() 前始终先调用此函数。

另请参阅：

IRINGERMGR_EnumNextCategory()

返回函数列表

IRINGERMGR_EnumNextCategory()

说明：

此函数用于枚举下一个振铃器类别。

原型：

boolean IRINGERMGR_EnumNextCategory
(
IRingerMgr * pIRingerMgr,
AEERingerCat * pi
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pi | 指向要填写的振铃器类别信息的指针。

返回值：

如果成功，则返回 TRUE。

如果函数失败或没有其它可枚举的类别，则返回 FALSE。

备注：

无

另请参阅：

AEERingerCat

IRINGERMGR_EnumCategoryInit()

返回函数列表

IRINGERMGR_EnumNextRinger()

说明：

此函数用于枚举下一个振铃器。

原型：

boolean IRINGERMGR_EnumNextRinger
(
IRingerMgr * pIRingerMgr,
AEERingerInfo * pi
)

参数：

pIRingerMgr | [in] | 指向 IRingerMgr 接口对象的指针。
pi | [out] | 指向要填写的振铃器信息的指针。

返回值：

如果成功，则返回 TRUE。

如果失败或没有其它可枚举的振铃器，则返回 FALSE。

备注：

此函数可重复调用。 请在调用此函数之前始终先调用 IRINGERMGR_EnumRingerInit()。

另请参阅：

AEERingerInfo

IRINGERMGR_EnumRingerInit()

返回函数列表

IRINGERMGR_EnumRingerInit()

说明：

此函数用于对振铃器列表的枚举进行初始化。

原型：

int IRINGERMGR_EnumRingerInit(IRingerMgr * pIRingerMgr)

参数：

pIRingerMgr
指向 IRingerMgr 接口对象的指针。

返回值：

如果已初始化枚举，则返回 SUCCESS。

如果类别无效，则返回 EFAILED。

其它特定于实现的错误代码

备注：

此函数可重复调用。 请在调用 IRINGERMGR_EnumNextRinger()
前始终先调用此函数。

另请参阅：

IRINGERMGR_EnumNextRinger()

返回函数列表

IRINGERMGR_GetFormats()

说明：

此函数用于填写所支持振铃器格式的列表。

原型：

int IRINGERMGR_GetFormats
(
IRingerMgr * pIRingerMgr,
AEESoundPlayerFile * pwFormats,
int nCount
)

参数：

pIRingerMgr | [in] | 指向 IRingerMgr 接口对象的指针。
pwFormats | [out] | 指向大小为 nCount * sizeof(AEESoundPlayerFile) 的格式列表的指针。
nCount | [in] | 要填写的格式条目数。

返回值：

如果缓冲区填满了振铃器格式条目，则返回 SUCCESS。

其它错误代码。

EFAILED，返回缓冲区的大小无效。

备注：

无

另请参阅：

AEESoundPlayerFile

IRINGERMGR_GetNumberFormats()

返回函数列表

IRINGERMGR_GetNumberFormats()

说明：

此函数用于获取设备支持的振铃器格式数。

原型：

int IRINGERMGR_GetNumberFormats(IRingerMgr * pIRingerMgr)

参数：

pIRingerMgr
指向 IRingerMgr 接口对象的指针。

返回值：

支持的振铃器格式数。

备注：

无

另请参阅：

IRINGERMGR_GetFormats()

返回函数列表

IRINGERMGR_GetRingerID()

说明：

此函数用于返回指定文件名振铃器的振铃器 ID。

原型：

AEERingerID IRINGERMGR_GetRingerID
(
IRingerMgr * pIRingerMgr,
const char * pszFile
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pszFile | 振铃器的根文件名。

返回值：

指定振铃器的 AEERingerID。

如果函数失败，则返回 AEE_RINGER_ID_NONE。

备注：

无

另请参阅：

AEERingerID

AEERingerInfo

返回函数列表

IRINGERMGR_GetRingerInfo()

说明：

该函数用于获取有关指定振铃器的信息。

原型：

int IRINGERMGR_GetNumberFormats
(
IRingerMgr * pIRingerMgr,
AEERingerID id,
AEERingerInfo * pi
)

参数：

pIRingerMgr | [in] | 指向 IRingerMgr 接口对象的指针。
id | [in] | 振铃器 ID。
pi | [out] | 指向要填写的振铃器信息结构的指针。

返回值：

如果振铃器信息有效，则返回 SUCCESS。

其它错误代码。

EFAILED，振铃器 ID 无效或 pi 为 NULL。

备注：

无

另请参阅：

AEERingerID

AEERingerInfo

返回函数列表

IRINGERMGR_Play()

说明：

此函数用于播放已安装的振铃器。

原型：

int IRINGERMGR_Play
(
IRingerMgr * pIRingerMgr,
AEERingerID id,
uint32 dwPause
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
id | 要播放的振铃器 ID。
dwPause | 连续两次播放间暂停的时间；如果是单次播放，则为 0（零）。

返回值：

如果开始播放振铃器，则返回 SUCCESS。

如果振铃器无效，则返回 EFAILED。

其它特定于实现的错误代码。

备注：

无

另请参阅：

AEERingerID

IRINGERMGR_Stop()

返回函数列表

IRINGERMGR_PlayEx()

说明：

此函数顺序使用以下项目作为源来播放指定的振铃器：

  • 已安装振铃器的 ID
  • 输入文件名
  • 输入 IAStream 对象

此操作允许调用程序先测试振铃器，再将其放入振铃器目录。

原型：

int IRINGERMGR_PlayEx
(
IRingerMgr * pIRingerMgr,
AEERingerID id,
const char * pszFile,
IAStream * pStream,
uint32 dwPause
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
id | 要播放的振铃器 ID。
pszFile | 输入文件名。
pStream | 输入流。
dwPause | 连续两次播放间暂停的时间；如果是单次播放，则为 0（零）。

返回值：

如果开始播放振铃器，则返回 SUCCESS。

其它错误代码。

如果振铃器无效，则返回 EFAILED。

备注：

无

另请参阅：

AEERingerID

IRINGERMGR_Stop()

返回函数列表

IRINGERMGR_PlayFile()

说明：

此函数用于在给出输入文件名时播放振铃器。 此操作允许调用程序先测试振铃器，

再将其放入振铃器目录。

原型：

int IRINGERMGR_PlayFile
(
IRingerMgr * pIRingerMgr,
const char * pszFile,
uint32 dwPause
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pszFile | 输入文件名。
dwPause | 连续两次播放间暂停的时间（如果是单次播放，则为 0）。

返回值：

如果开始播放振铃器，则返回 SUCCESS。

如果振铃器无效，则返回 EFAILED。

其它特定于实现的错误代码。

备注：

无

另请参阅：

IRINGERMGR_Stop()

返回函数列表

IRINGERMGR_PlayStream()

说明：

此函数可以使用 IAStream 接口 输入对象播放指定振铃器。该操作允许调用程序测试可能位于文件（IFile 接口）、内存（IMemAStream 接口）或整个网络（ISocket 接口）中的振铃器。

原型：

int IRINGERMGR_PlayStream
(
IRingerMgr * pIRingerMgr,
IAStream * pStream,
uint32 dwPause
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pStream | 输入文件名。
dwPause | 连续两次播放间的暂停时间（以毫秒为单位）；如果是单次播放， 则为 0（零）。

返回值：

如果开始播放振铃器，则返回 SUCCESS。

如果振铃器无效，则返回 EFAILED。

其它特定于实现的错误代码。

备注：

此函数仅支持来自 TCP 套接字的网络流，而不支持来自 UDP 套接字的网络流。

另请参阅：

无

返回函数列表

IRINGERMGR_RegisterNotify()

说明：

此函数用于在完成播放或创建事件时注册或撤消注册通知回调。

原型：

void IRINGERMGR_RegisterNotify
(
IRingerMgr * pIRingerMgr,
PFNRINGEREVENT pfn,
void * pUser
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
pfn | 指向用户回调的指针（NULL 用于注销）。
pUser | 指向回调所需用户数据的指针。 如果无需标识数据，该指针可以指向 NULL。

返回值：

无

备注：

无

另请参阅：

PFNRINGEREVENT

返回函数列表

IRINGERMGR_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IRINGERMGR_AddRef()

返回函数列表

IRINGERMGR_Remove()

说明：

此函数用于删除指定的振铃器。

原型：

int IRINGERMGR_Remove(IRingerMgr * pIRingerMgr, AEERingerID id)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
id | 振铃器 ID。

返回值：

如果已删除振铃器，则返回 SUCCESS。

如果振铃器无效，则返回 EFAILED。

其它特定于实现的错误代码。

备注：

此函数不能用于删除 OEM 安装的振铃器。

另请参阅：

AEERingerID

返回函数列表

IRINGERMGR_SetRinger()

说明：

此函数使调用程序可以从选定类别中指定要播放的振铃器。

原型：

int IRINGERMGR_SetRinger
(
IRingerMgr * pIRingerMgr,
AEERingerCatID idCat,
AEERingerID id
)

参数：

pIRingerMgr | 指向 IRingerMgr 接口对象的指针。
idCat | 振铃器类别。
id | 振铃器 ID。

返回值：

如果已设置振铃器，则返回 SUCCESS。

其它错误代码。

EFAILED，未设置振铃器。

备注：

无

另请参阅：

AEERingerID

AEERingerCatID

IRINGERMGR_EnumNextCategory()

返回函数列表

IRINGERMGR_Stop()

说明：

此函数用于终止播放振铃器。

原型：

int IRINGERMGR_Stop(IRingerMgr * pIRingerMgr)

参数：

pIRingerMgr
指向 IRingerMgr 接口对象的指针。

返回值：

如果振铃器正在停止，则返回 SUCCESS。

其它错误代码。

EFAILED，未播放振铃器。

备注：

无

另请参阅：

IRINGERMGR_Play()

返回函数列表


IShell 接口

IShell 接口的函数可以为 BREW 应用程序提供多种服务。 本节包含 IShell 接口函数的高级
概述，其中每小节说明一组相关函数。

警报

当前时间到达指定值时，AEE 外壳警报函数将通知应用程序。 与只在应用程序运行时才被激活的计时器不同，即使应用程序不在运行也可以接收警报过期的通知。 当通知的时间在比较远的将来时，通常使用警报。 例如，日程约会时间将要来临时，日程应用程序将使用警报提醒用户。

要设置警报，请调用 ISHELL_SetAlarm() 函数，指定从当前时间算起距离警报通知发生时间的分钟数、16 位警报代码、以及到达警报时间时接收通知的应用程序（您的或他人的）
的 BREW ClassID。 通知发生时，使用 EVT_ALARM 事件和 16 位警报代码作为参数，调用被通知应用程序的 IAPPLET_HandleEvent() 函数。 后一个参数使得应用程序能够区别多个同时激活的警报。 如果被通知的应用程序当前未在运行，AEE 外壳将创建它的一个实例来处理通知事件，完成后即终止该实例。 如果有必要，应用程序可以选择激活自身。 AEE 外壳将警报保存在 BREW 数据库中，并在启动 BREW 设备时不断检查警报的到期时间。 如果警报到期时设备是关闭的，则 AEE 外壳将在下次启动设备时生成通知。

ISHELL_CancelAlarm() 用于取消当前激活的警报。ISHELL_AlarmsActive() 用于检查任一 BREW 内置报警器（闹钟、倒数计时器或秒表）当前是否处于激活状态。

应用程序管理

AEE 外壳的应用程序管理函数可提供以下功能：

  • 创建、启动和终止 BREW 类和应用程序
  • 获取设备上的模块和类的信息
  • 允许应用程序互相发送事件
  • 允许运行 BREW 应用程序，而不干扰设备必须执行的其它活动

ISHELL_CreateInstance() 用于创建设备模块支持的 BREW 类实例和用户自定义类实例。ISHELL_StartApplet() 函数允许运行指定的小程序。 如果必要，该函数可以创建一个小程序实例，中止当前正在运行的小程序（如果有），然后以 EVT_APP_START 事件为参数调用指定小程序的 IAPPLET_HandleEvent() 函数，从而运行该小程序。ISHELL_CloseApplet() 将 EVT_APP_STOP 事件发送给当前正在运行的小程序，并调用其释放函数。ISHELL_CloseApplet() 主要用于 AEE 外壳自身，因为不可能使用一个小程序终止另一个
小程序。

ISHELL_ActiveApplet() 用于获取当前正在运行的小程序的 ClassID。ISHELL_EnumAppletInit() 和 ISHELL_EnumNextApplet() 可用于枚举设备模块中的小程序。 枚举小程序时，ISHELL_EnumNextApplet() 将返回指向小程序 AEEAppInfo 数据结构的指针。该结构可以标识小程序的 MIF 文件、标题、图标和类型（游戏、工具、PIM 和其它类型）。ISHELL_QueryClass() 函数用于确定设备上是否存在某个类。 如果该类为小程序，
则将提供指向 AEEAppInfo 数据结构的指针，其中填充了相关的信息（如果小程序可用）。

ISHELL_SendEvent() 用于向指定的类发送事件。 如果当前没有该类的实例，AEE 外壳将创建一个实例，然后使用指定的事件代码和数据参数调用 IAPPLET_HandleEvent() 函数。
除非应用程序选择自动启动，否则应用程序将在完成事件处理后终止。除了不会立即调用目标类的 IAPPLET_HandleEvent() 函数之外，ISHELL_PostEvent() 与之类似。 事件放置在队列中稍后发送，这允许调用的程序继续执行，而不会中断。如果接收事件的类标识未知，则可以使用 ISHELL_HandleEvent()。 这时，AEE 外壳将把事件发送给当前运行的小程序或它的活动对话框（如果有）。

AEE 外壳包含了若干函数，使得 BREW 应用程序可与设备上的其它活动共存。 BREW 应用程序模型基于协作多任务处理设计，这意味着每个应用程序在处理事件时只能运行尽可能短的时间，然后退出以便运行设备上的其它活动。

ISHELL_Busy() 使 BREW 应用程序可以确定设备上是否存在其它正在进行的活动要求它立即退出。ISHELL_ForceExit() 的作用与 ISHELL_Busy() 相同。ISHELL_Resume() 允许应用程序将耗时的任务分解为更小的可中断程序块。 每个程序块由回调函数及关联的数据指针表示。 ISHELL_Resume() 用于调度以后要调用的回调函数（数据指针是其唯一参数）。 ISHELL_CanStartApplet() 用于检查能否启动 BREW 应用程序，如果设备上正在运行优先级较高的活动，则可能返回非 true 值。

对话框、消息框和提示

对话框由包含一个或多个 BREW 控件的屏幕组成，允许设备用户输入数据或选择菜单项目。 尽管可以使用 BREW 控件接口（IDateCtl 接口、IMenuCtl 接口、ITextCtl 接口 和 ITimeCtl 接口）创建屏幕，但 IDialog 接口可以大大简化该任务：

  • 使用 BREW 资源编辑器创建对话框，包括对话框中每个控件的规格。 有关详细信息，请参阅《BREW 资源编辑器指南》。
  • BREW AEE 可维护与当前运行的程序相关联的对话框栈。 创建对话框时，会将对话框置于栈顶；结束对话框时，则将其从栈内删除，并恢复其下面的对话框。 这样可以轻松实现能够引导设备用户贯穿屏幕序列（例如，菜单分级体系）的应用程序。
  • 处于激活状态的对话框将接收所有事件，并将事件分配给当前激活的控件。 对话框也处理控件切换，允许设备用户在多控件对话框中的控件之间移动焦点。 这样您便无需实现分配和处理这些事件的代码。

ISHELL_CreateDialog() 用于创建对话框。 此函数可接受 BREW 资源编辑器所创建对话框的标识符，或数据结构指针（其中填充了指定对话框控件的代码）作为输入。 如果成功，
函数将在屏幕上显示对话框控件，并将对话框推入对话框堆栈。 要结束对话框，可以调用 ISHELL_EndDialog()终止栈顶对话框，并立即显示其下面的对话框。 此函数还可以向应用程序发送 EVT_DIALOG_END 事件，允许执行与终止对话框相关的所有处理，例如获取设备用户在对话框控件中输入的值。ISHELL_EndDialog() 还可释放对话框使用的所有资源。

ISHELL_CreateDialog() 不返回指向所创建对话框的接口指针。ISHELL_GetActiveDialog() 用于获取栈顶对话框的 IDialog 接口指针。 使用此指针可调用组成 IDialog 接口的函数： IDIALOG_SetFocus() 用于返回任一对话框控件的接口指针，IDIALOG_SetFocus() 用于指定多控件对话框中接收设备用户输入的控件。

AEE 外壳还提供了一些通过一次调用即可创建简单常用对话框的函数。ISHELL_Prompt() 用于显示带软键控制菜单的对话框，提示设备用户作出选择。 设备用户作出选择后，使用 EVT_COMMAND 将选择返回到应用程序并自动终止该对话框。 还有两个函数可创建显示只读文本消息和标题的对话框。ISHELL_MessageBox() 用于从 BREW 资源文件中读取标题和消息文本，ISHELL_MessageBoxText() 则用于接受指向代码中指定的标题和消息文本字符串的指针。 设备用户按下按键时，将结束这些函数创建的对话框。


设备和应用程序配置信息

这些函数允许获取关于设备及特定应用程序的配置信息。ISHELL_GetDeviceInfo() 可返回指向设备的 AEEDeviceInfo 结构的指针，其中包括它的屏幕大小、支持的颜色、可用内存量、字符编码以及其它项目的相关信息。

ISHELL_GetPrefs() 和 ISHELL_SetPrefs() 提供了应用程序注册配置信息的通用机制。 ISHELL_SetPrefs() 函数用于将配置数据指针和该数据的版本号与应用程序的 ClassID 关联。 其它应用程序可使用指定的 ClassID 和版本号作为参数调用 ISHELL_GetPrefs() 来获取这些数据。 您还必须提供结构声明，定义各版应用程序配置数据的内容。


其它

ISHELL_Beep() 允许应用程序为设备用户提供多种声音信号或振动信号。 根据给定设备支持的对象，可以为关闭设备、警告、提醒、消息到达和错误事件设置声音信号，为警告和提醒设置振动信号。 您可以指定布尔响度参数。


通知

IShell 的通知机制允许 BREW 类相互通知发生的特定事件。 要接收通知，已激活的类必须向 AEE 外壳注册，指定通知类的 ClassID 和通知的事件。 当发生需要通知的事件时，通知程序类将调用 ISHELL_Notify()，向每个已注册接收该事件通知的类发送通知。

AEE 外壳为类提供了两个注册方法以接收事件通知：

  • 通过 MIF 编辑器指定有关应用程序 MIF 文件中的通知信息进行注册。 即使未在运行也必须接收事件通知的应用程序可以使用这种注册方法。 例如接收每个进入和外发呼叫通知的呼叫日志应用程序， 即使设备用户没有运行该应用程序显示呼叫日志，应用程序也必须处理通知。
  • 如果仅在应用程序运行的特定时间内需要进行通知，则可以调用 ISHELL_RegisterNotify() 启动事件通知。 例如，游戏应用程序在进入呼叫到达时可能显示一条消息，允许设备用户接受呼叫或继续游戏。 应用程序仅要求在设备用户正在游戏时通知进入的呼叫，因此设备用户开始游戏时将调用 ISHELL_RegisterNotify()。

通知程序类用于提供事件通知，该事件由 32 位变量表示。 变量的低 16 位包含通知掩码，
其中每一位都对应一个事件。 变量的高 16 位包含通知程序匹配值，可用于事件所关联的数据。 例如，表示 UDP 套接字活动的事件使用发生该活动的端口匹配值。 注册接收通知时，类提供掩码变量值，将其中每个相关事件的位都设置为 1。如果类不再需要某个事件通知，可以将掩码变量中该事件的位设置为 0（零）调用 ISHELL_RegisterNotify()。 例如应用程序终止时，可能将掩码变量设置为 0（零）调用 ISHELL_RegisterNotify()。

注意： 当其它类注册以接收事件通知时，AEE 外壳将创建一个通知类的实例。 当所有类均已注销事件通知时，将释放该实例。

通知类调用 ISHELL_Notify() 时，AEE 外壳将 EVT_NOTIFY 类型事件发送给每个注册接收事件通知的应用程序。 这将使应用程序调用其 IAPPLET_HandleEvent() 函数。 如果应用程序当前没在运行，AEE 外壳将创建它的实例来处理事件，完成后即终止该应用程序。 如果应用程序想继续运行，也可以给自身发送启动事件。 调用 IAPPLET_HandleEvent() 时，还将向应用程序传递一个 AEENotify 类型的结构指针，该指针用于标识发生的事件、生成通知的类及特定于通知的一些附加数据。

当前，INetMgr 类可以向其它相关类发送网络连接状态更改和特定 UDP 端口到达数据的通知。 此外，您还可以实现自己的通知程序类， 且该类必须实现 INotifier 接口
（有关定义类时如何声明该接口的详细信息，请参阅通知应用程序示例）。 INotifier 接口要求您实现类的 INOTIFIER_SetMask() 函数。 只要其它类注册接收该类发出的事件通知，AEE 外壳即会调用此函数。INOTIFIER_SetMask() 仅包含一个 32 位的变量参数，是每个注册接收该类通知的类使用的掩码变量的逻辑“或”。 只要至少一个类注册了接收对应的事件通知，该变量即会有一位的值为 1。 当类首次注册要接收事件通知时，可使用该变量执行任何所需的初始化，如果没有任何类需要特定事件的通知时，可使用该变量完成结束操作。

为您的类提供通知程序功能

  1. 提供包含文件，其中包含分配给每个通知事件的位定义常量以及作为事件通知一部分的事件特定数据的 typedef。 注册接收您的类通知的应用程序将使用该包含
    文件。
  2. 只要发生通知事件，且至少有一个类已注册接收该通知事件，就将调用 ISHELL_Notify()。


资源文件和文件处理程序

应用程序可以使用 AEE 外壳提供的许多函数从文件中读取各类数据。 这些文件可以是使用 BREW 资源编辑器创建的 BREW 资源 (.bar) 文件，也可以是内容与 MIME 类型相关或由文件扩展名标识的文件。 您还可以通过定义自己的处理程序类并使用它们操作特定 MIME 类型的文件，来扩展 BREW AEE 可以识别的文件类型集。

请使用以下函数访问 BREW 资源文件。 每个函数的参数包括资源文件名称和整型资源 ID：

  • 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() 可用于直接加载图像和声音文件，而不必首先将它们的内容放入 BREW 资源文件。 该文件必须包含 BREW AEE 支持的一种内部 MIME 类型，如 Windows 位图 (.BMP) 或设备特定的图像原位图格式，以及 MIDI (.midi) 或 CMX (.cmx) 声音文件。

ISHELL_RegisterHandler() 用于将 MIME 文件类型与为处理该类型文件而实现的 BREW 处理程序类的 ClassID 相关联。ISHELL_GetHandler() 用于返回与给定 MIME 类型相关联的处理程序类的 ClassID，包括上文提到的 BREW 内置类型。

ISHELL_GetHandler() 用于获取文件的 MIME 类型处理程序类的 ClassID。

ISHELL_CreateInstance() 用于创建处理程序类的实例。


计时器

当前实例化应用程序（其引用计数非零）可以使用 AEE 外壳的计时器，在超过指定的时间段后执行某项操作。 这些时间段一般很短（以秒或毫秒计算）。 如果需要经过较长的时间段，则可以使用 AEE 外壳的警报函数获取通知（即使应用程序当前没有实例化）。

ISHELL_GetTimerExpiration() 用于确定特定计时器到期之前剩余的毫秒数。 计时器由回调函数和创建计时器时提供的数据结构地址来标识。ISHELL_CancelTimer() 用于取消正在运行的计时器。 如果将回调函数的参数设置为 NULL，则将取消与指定数据结构地址相关联的所有计时器。 如果应用程序实例的引用计数减为 0（零），则将取消与该应用程序相关联的所有
计时器。

要包含的头文件列表

需要以下头文件：

AEEShell.h

函数列表

此接口的函数包括：

ISHELL_ActiveApplet()

ISHELL_AddRef()

ISHELL_AlarmsActive()

ISHELL_Beep()

ISHELL_BrowseFile()

ISHELL_BrowseURL()

ISHELL_Busy()

ISHELL_CancelAlarm()

ISHELL_CancelTimer()

ISHELL_CanStartApplet()

ISHELL_CheckPrivLevel()

ISHELL_CloseApplet()

ISHELL_CreateDialog()

ISHELL_CreateInstance()

ISHELL_DetectType()

ISHELL_EndDialog()

ISHELL_EnumAppletInit()

ISHELL_EnumNextApplet()

ISHELL_ForceExit()

ISHELL_FreeResData()

ISHELL_GetActiveDialog()

ISHELL_GetAppAuthor()

ISHELL_GetAppCopyright()

ISHELL_GetAppPrefs()

ISHELL_GetAppVersion()

ISHELL_GetDeviceInfo()

ISHELL_GetDeviceInfoEx()

ISHELL_GetHandler()

ISHELL_GetItemStyle()

ISHELL_GetJulianDate()

ISHELL_GetPosition()

ISHELL_GetPrefs()

ISHELL_GetRand()

ISHELL_GetResSize()

ISHELL_GetSeconds()

ISHELL_GetTimeMS()

ISHELL_GetTimerExpiration()

ISHELL_GetUpTimeMS()

ISHELL_HandleEvent()

ISHELL_IsValidResource()

ISHELL_LoadBitmap()

ISHELL_LoadBusyImage()

ISHELL_LoadImage()

ISHELL_LoadResBitmap()

ISHELL_LoadResData()

ISHELL_LoadResDataEx()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_LoadSound()

ISHELL_MessageBox()

ISHELL_MessageBoxText()

ISHELL_Notify()

ISHELL_OnAppClose()

ISHELL_OnExit()

ISHELL_OnInit()

ISHELL_OnLowRAM()

ISHELL_OnLowStorage()

ISHELL_OnModUnload()

ISHELL_PostEvent()

ISHELL_Prompt()

ISHELL_QueryClass()

ISHELL_RegisterHandler()

ISHELL_RegisterNotify()

ISHELL_RegisterSystemCallback()

ISHELL_Release()

ISHELL_Resume()

ISHELL_SendEvent()

ISHELL_SetAlarm()

ISHELL_SetAppPrefs()

ISHELL_SetPrefs()

ISHELL_SetTimer()

ISHELL_SetTimerEx()

ISHELL_ShowCopyright()

ISHELL_StartApplet()

ISHELL_StartAppletArgs()

ISHELL_StartAppletEx()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISHELL_ActiveApplet()

说明：

此函数用于返回当前运行的小程序所关联的 AEECLSID。

原型：

AEECLSID ISHELL_ActiveApplet(IShell * pIShell)

参数：

pIShell（可用）
指向 IShell 接口对象的指针。

返回值：

如果小程序正在运行，则返回活动小程序的 ID。

如果没有正在运行的小程序，则返回 0（零）。

备注：

无

另请参阅：

AEECLSID 列表

ISHELL_StartApplet()

ISHELL_CloseApplet()

ISHELL_CanStartApplet()

返回函数列表

ISHELL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISHELL_Release()

返回函数列表

ISHELL_AlarmsActive()

说明：

如果已设置 ANNUN_ALARMCLOCK、ANNUN_COUNTDOWN 或 ANNUN_STOPWATCH，则此函数将返回 TRUE。 此函数不检验任何其它类型的
警报。

注意：由于 BREW Emulator 不支持报警器，因此也不支持此函数。

原型：

boolean ISHELL_AlarmsActive(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果有激活的报警器，则返回 TRUE。

如果没有激活的报警器，则返回 FALSE。

备注：

在 Windows 中，此函数始终返回 FALSE，因为 BREW Emulator 不支持报警器。

另请参阅：

IDISPLAY_SetAnnunciators()

返回函数列表

ISHELL_Beep()

说明：

此函数用于提供简单的接口来播放系统蜂鸣声或振动设备。

原型：

boolean ISHELL_Beep(IShell * pIShell, BeepType nBeep, boolean bLoud)

参数：

pIShell | 指向 IShell 接口对象的指针。
nBeep | 要播放的蜂鸣类型。
bLoud | 如果能以更高的音量播放蜂鸣声，则为 TRUE。

返回值：

如果播放了蜂鸣声，则返回 TRUE。

如果未播放蜂鸣声，则返回 FALSE。

备注：

在 BREW Emulator 中，用户可以 .WAV 格式定义自己的蜂鸣类型音调。 蜂鸣类型对应于 ISHELL_Beep() 中要求的 BeepType 枚举。 音调保存在 <$BREWDIR\bin\DataFiles> 目录下。 例如，要创建 BEEP_ALERT 音调，需将 WAV 文件保存为 BEEP_ALERT.wav。

BREW SDK 附带了所有蜂鸣类型的音调文件。 示例声音小程序提供了对 ISHELL_Beep() 的说明。

另请参阅：

BeepType

返回函数列表

ISHELL_BrowseFile()

说明：

此函数可尝试为路径 pszFile 所给出文件的扩展名查找关联的注册小程序。 如果找到处理小程序，则此函数将创建它的实例，并将 EVT_APP_START 事件发送给该实例。 如果小程序启动成功，ISHELL_BrowseFile() 将向小程序发送 EVT_APP_BROWSE_FILE 事件与文件路径， 处理小程序即可浏览该文件。

原型：

void ISHELL_BrowseFile (IShell * pIShell, const char * pszFile)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszFile | 包含要浏览的文件名的字符串指针。 文件的扩展名（如，htm）可用于定位浏览文件的处理小程序。

返回值：

无

备注：

无

另请参阅：

ISHELL_RegisterHandler()

ISHELL_GetHandler()

ISHELL_BrowseURL()

返回函数列表

ISHELL_BrowseURL()

说明：

此函数可尝试为 pszURL 所指向字符串中的 URL 资源类型查找相关联的注册小程序。 如果找到处理小程序，则此函数将创建它的实例，并将 EVT_APP_START 事件发送给该实例。 如果小程序启动成功，ISHELL_BrowseURL() 将向小程序发送 EVT_APP_BROWSE_URL 事件与 URL， 处理小程序即可浏览 URL。

原型：

void ISHELL_BrowseURL (IShell * pIShell, const char * pszURL)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszURL | 包含要浏览的 URL 的字符串指针。 URL 资源类型（如，http 或 mailto）用于定位浏览 URL 的处理小程序。

返回值：

无

备注：

无

另请参阅：

ISHELL_RegisterHandler()

ISHELL_GetHandler()

ISHELL_BrowseFile()

返回函数列表

ISHELL_Busy()

说明：

如果小程序必须退出，则此函数将返回 TRUE。 它是浏览器或其它应用程序仅为特殊用途提供的函数，可在返回 ISHELL_HandleEvent() 之前，进行大量的处理。

原型：

boolean ISHELL_Busy(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果小程序必须停止处理并退出，则返回 TRUE。

如果小程序可以继续处理，则返回 FALSE。

备注：

该函数使用 ISHELL_ForceExit()。

另请参阅：

ISHELL_ForceExit()

返回函数列表

ISHELL_CancelAlarm()

说明：

此函数用于取消通过 ISHELL_SetAlarm() 设置的警报。 必须指定适当的类和 16 位用户代码。

原型：

int ISHELL_CancelAlarm
(
IShell * pIShell,
AEECLSID cls,
uint16 nUserCode
)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 要取消警报的小程序类。
nUserCode | 要取消警报的 16 位用户代码。

返回值：

如果找到并取消警报，则返回 SUCCESS。

如果没有找到或取消警报，则返回 EFAILED。

备注：

无

另请参阅：

AEECLSID 列表

ISHELL_SetAlarm()

返回函数列表

ISHELL_CancelTimer()

说明：

此函数用于取消使用 ISHELL_SetTimer() 设置的计时器。 如果 pfn 不是 NULL，则取消与 pfn 和 pUser 相关联的计时器。 如果 pfn 为 NULL，则取消与 pUser 相关联的所有计时器。

原型：

int ISHELL_CancelTimer(IShell * pIShell, PFNNOTIFY pfn, void * pUser)

参数：

pIShell | 指向 IShell 接口对象的指针。
pfn | 用户回调。
pUser | 用户数据。

返回值：

始终返回 SUCCESS。

备注：

尝试取消未设置的计时器不会有影响。

另请参阅：

PFNNOTIFY

ISHELL_SetTimer()

ISHELL_GetTimerExpiration()

返回函数列表

ISHELL_CanStartApplet()

说明：

此函数用于查询 AEE 外壳来确定启动小程序是否安全。 正常条件下，该调用将返回 TRUE。 但在某些情况下，如正在显示关键对话框或运行其它小程序时，可能会阻止启动新的小程序。

原型：

boolean ISHELL_CanStartApplet(IShell * pIShell, AEECLSID cls)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 要检查的小程序的 ClassID。

返回值：

如果可以安全启动小程序，则返回 TRUE。

如果启动小程序不安全，则返回 FALSE。

备注：

无

另请参阅：

AEECLSID 列表

ISHELL_StartApplet()

ISHELL_CloseApplet()

ISHELL_ActiveApplet()

返回函数列表

ISHELL_CheckPrivLevel()

说明：

此函数可依据指定值检查当前正在运行的应用程序的优先级。 如果优先级匹配，
函数将返回 TRUE。 否则，将返回 FALSE，并使用系统消息有条件地终止应用程序。

原型：

boolean ISHELL_CheckPrivLevel
(
IShell * pIShell,
uint16 wPrivWant,
boolean bQueryOnly
)

参数

pIShell | 指向 IShell 接口对象的指针。
wPrivWant | 要检查的指定优先位。
bQueryOnly | 如果是 TRUE，则仅为一项查询。 如果是 FALSE，且没有 wPrivWant 中指定的优先级，则应用程序将终止。

返回值：

如果应用程序支持该优先级掩码，则返回 TRUE。

如果应用程序不支持该优先级，则返回 FALSE。

备注：

如果 bQueryOnly 为 FALSE，且函数返回 FALSE，则终止应用程序时不会作进一步的处理。

另请参阅：

无

返回函数列表

ISHELL_CloseApplet()

说明：

此函数用于指示 AEE 外壳关闭激活的小程序。 小程序将得到 EVT_APP_STOP 消息，并调用 EVT_APP_STOP。 bReturnToIdle 参数指示 AEE 是否必须关闭其它所有激活的应用程序，并返回空闲屏幕。

原型：

int ISHELL_CloseApplet(IShell * pIShell, boolean bReturnToIdle)

参数：

pIShell | 指向 IShell 接口对象的指针。
bReturnToIdle | 该参数指示 AEE 外壳是否必须关闭其它所有激活的应用程序，并返回空闲屏幕。

返回值：

如果操作成功，则返回 SUCCESS。

如果操作失败，则返回 EFAILED。

备注：

BREW Emulator 不支持 bReturnToIdle。

另请参阅：

ISHELL_StartApplet()

ISHELL_CanStartApplet()

ISHELL_ActiveApplet()

返回函数列表

ISHELL_CreateDialog()

说明：

此函数用于指示 AEE 外壳启动与输入 DialogInfo 数据结构或相关资源文件中对话框信息相关联的对话框。 此调用可使 AEE 外壳创建 IDialog 接口。 该接口将处理对话框输入参数，以创建所有相关控件和其它项目。 该对话框将放置在激活的对话框堆栈栈顶。

在创建、执行和终止过程中，IDialog 接口将向激活的小程序发送若干与对话框有关的 AEE 事件（如 EVT_DIALOG_INIT、EVT_DIALOG_START
和 EVT_DIALOG_END）。 这样将允许小程序控制控件的初始内容、管理控件的更改，并在终止时再次获取控件内容。 通过调用 IDIALOG_GetControl()，小程序可以获取指向底层对话框控件的指针。

原型：

int ISHELL_CreateDialog
(
IShell * pIShell,
const char * pszResFile,
uint16 wID,
DialogInfo * pInfo
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 指向包含对话框信息的资源文件的指针。
wID | 资源文件内部的对话框 ID。
pInfo | 其它对话框信息结构。 如果提供该结构，则将忽略 pszResFile 和 wID。

返回值：

如果成功，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果参数无效，则返回 EBADPARM。

如果失败，则返回 EFAILED。

备注：

无

另请参阅：

DialogInfo

ISHELL_GetActiveDialog()

ISHELL_EndDialog()

IDIALOG_SetFocus()

IDIALOG_GetControl()

EVT_DIALOG_INIT

EVT_DIALOG_START

EVT_DIALOG_END

返回函数列表

ISHELL_CreateInstance()

说明：

此函数用于创建具有指定的 32 位 ClassID 的对象。 返回的对象必须与该 ClassID 支持的接口相匹配。 如果成功，则 ppobj 中将填入指定类的对象，并且所返回对象的引用计数为正。

原型：

int ISHELL_CreateInstance
(
IShell * pIShell,
AEECLSID cls,
void * * ppobj
)

参数：

pIShell | [in] | 指向 IShell 接口对象的指针。
cls | [in] | 请求的接口的 32 位 ClassID。
ppobj | [out] | 指向用对象指针填充的内存的指针。

返回值：

如果已创建类，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持指定的类，则返回 ECLASSNOTSUPPORT。

备注：

无

另请参阅：

AEECLSID 列表

IMODULE_CreateInstance()

返回函数列表

ISHELL_DetectType()

说明：

给定缓冲区数据或对象名称，此函数可以检测 MIME 类型。

它通常用于获取数据类型关联的处理程序。 例如，如果数据代表 MIDI 标准格式，则此函数将返回 MIME "audio/mid"。 使用 MIME 类型可以查询外壳注册，以获取 AEECLSID_MEDIA 类型的处理程序（类 ID）。

原型：

int ISHELL_DetectType
(
IShell * pIShell,
const void * cpBuf,
uint32 * pdwSize,
const char * cpszName,
const char
** pcpszMIME
);

参数：

pIShell | [in] | 指向 IShell 对象的指针
cpBuf | [in] | 包含需要确定类型的数据的缓冲区
pdwSize | [in/out] | 输入时： pBuf 中的数据大小（如果 pBuf 为 NULL，则忽略） 输出时： 执行类型检测需要的附加数据字节数
cpszName | [in] | 需要确定类型的对象的名称（如果未知，则为 NULL）。
pcpszMIME | [out] | 返回到调用程序的 MIME 字符串，返回时，已填入指向常量字符串（不释放）的指针

返回值：

SUCCESS： 已检测到数据类型，并已返回 MIME

ENOTYPE： 没有与此数据关联的类型

EBADPARM： 错误的输入数据（参数）

ENEEDMORE： 需要更多数据才能执行类型检测。 *pdwSize 包含需要的附加字节数。

EUNSUPPORTED： 不支持指定输入的类型检测

备注：

pBuf 优先于 pszName。 如果两者均已指定，则首先使用 pBuf 进行类型检测，然后使用 pszName。

如果函数返回 ENEEDMORE，则将执行此操作需要的附加字节数填入 *pdwSize，
并请使用（原始 dwSize + *pdwSize）字节为参数再次调用此函数。

要确定实现类型检测需要的最大字节数，可执行以下代码：

if (ENEEDMORE == ISHELL_DetectType(ps, NULL, &dwReqSize, NULL, NULL))
{
// dwReqSize 包含类型检测所需的最大字节数
}

典型用法： 以下代码根据缓冲区数据创建基于 IMedia 的对象，并启动媒体播放。

//--------------- 开始 -----------------------------
// 假定，
// pIShell： 指向 IShell 的指针
// pBuf： 包含多媒体格式（基于 IMedia）数据的缓冲区
// dwSize： 缓冲区的大小
//
const char * cpszMIME;
AEECLSID clsHandler;
IMedia * pMedia;
if (SUCCESS == ISHELL_DetectType(pIShell, pBuf, &dwSize, NULL, &cpszMIME)
{
// 查询 AEECLSID_MEDIA（例如 IMedia）类型的处理程序
clsHandler = ISHELL_GetHandler(pIShell, AEECLSID_MEDIA,
cpszMIME);
if (clsHandler)
{
if (SUCCESS == ISHELL_CreateInstance(pIShell, clsHandler,
(void **)&pMedia))
{
// 开始使用 IMedia 接口...
IMEDIA_Play(pMedia); // 开始播放
:
:
}
}
}
//--------------- 结束 --------------------------------

另请参阅：

ISHELL_GetHandler()

ISHELL_CreateInstance()

返回函数列表

ISHELL_EndDialog()

说明：

此函数用于关闭当前激活的对话框。

原型：

ISHELL_EndDialog(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果成功关闭激活的对话框，则返回 SUCCESS。

如果没有激活的对话框，则返回 EFAILED。

备注：

无

另请参阅：

ISHELL_CreateDialog()

ISHELL_GetActiveDialog()

IDIALOG_SetFocus()

IDIALOG_GetControl()

返回函数列表

ISHELL_EnumAppletInit()

说明：

此函数用于重置 AEE 外壳的内部小程序枚举索引。

原型：

void ISHELL_EnumAppletInit(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

无

备注：

此函数应与 ISHELL_EnumNextApplet() 联合使用，如以下示例所示：

ISHELL_EnumAppletInit(pShell);
while(ISHELL_EnumNextApplet(pShell, &ai)){process...}

另请参阅：

ISHELL_EnumNextApplet()

返回函数列表

ISHELL_EnumNextApplet()

说明：

此函数用于返回下一个小程序的信息。

原型：

AEECLSID ISHELL_EnumNextApplet(IShell * pIShell, AEEAppInfo * pai)

参数：

pIShell | 指向 IShell 接口对象的指针。
pai | 指向要填充的 AEEAppInfo 结构的指针。

返回值：

如果成功，则返回下一个小程序的 ClassID。

如果没有更多可枚举的小程序或 pai 为 NULL，则返回 0（零）。

备注：

此函数应与 ISHELL_EnumAppletInit() 联合使用，如以下示例所示：

ISHELL_EnumAppletInit(pShell);
while(ISHELL_EnumNextApplet(pShell, &ai)){process...};

另请参阅：

AEECLSID 列表

AEEAppInfo

ISHELL_EnumAppletInit()

返回函数列表

ISHELL_ForceExit()

说明：

如果小程序必须退出，则此函数将返回 TRUE。 它是浏览器或其它应用程序仅为特殊用途提供的函数，可在返回 ISHELL_HandleEvent() 之前，进行大量的处理。

原型：

boolean ISHELL_ForceExit(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果小程序必须停止处理并退出，则返回 TRUE。

如果小程序可以继续处理，则返回 FALSE。

备注：

无

另请参阅：

ISHELL_Busy()

返回函数列表

ISHELL_FreeResData()

说明：

此函数用于释放之前由 ISHELL_LoadResData() 返回的数据。

原型：

void ISHELL_FreeResData(IShell * pIShell, void * pData)

参数：

pIShell | 指向 IShell 接口对象的指针。
pData | 要释放的资源数据，必须先调用 ISHELL_LoadResData() 返回。

返回值：

无

备注：

无

另请参阅：

ISHELL_LoadResData()

返回函数列表

ISHELL_GetActiveDialog()

说明：

此函数用于返回当前激活的对话框。 此函数可使小程序查询底层控件和其它项目
对话框。

原型：

IDialog * ISHELL_GetActiveDialog(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果成功，则返回指向当前激活对话框的指针。

如果没有激活的对话框或失败，则返回 NULL。

备注：

无

另请参阅：

ISHELL_CreateDialog()

ISHELL_EndDialog()

IDIALOG_SetFocus()

IDIALOG_GetControl()

返回函数列表

ISHELL_GetAppAuthor()

说明：

此方法允许调用程序检索活动小程序作者的姓名。 该信息可以从当前小程序的 MIF 中获取。 此函数将在指定的字符串缓冲区中，返回 MIF 的“作者姓名”字段
（MIF 编辑器早期版本中为“公司名称”）中输入的字符串。

原型：

int ISHELL_GetAppAuthor(IShell * pIShell, AECHAR * pBuff, int nSize);

参数：

pIShell | 指向 IShell 对象的指针
pBuff | 要填入作者姓名字符串的缓冲区
nSize | 输入缓冲区大小（字节）

返回值：

填入的字节数。 如果没有找到作者姓名字符串或缓冲区 pBuff 为 NULL，则返回 0

备注：

无

另请参阅：

无

返回函数列表

ISHELL_GetAppCopyright()

说明：

此方法允许调用程序检索活动小程序的版权字符串。 此信息可以从 MIF 中获取。

原型：

int ISHELL_GetAppCopyright
(
IShell * pIShell,
AECHAR * pBuff,
int nSize
)

参数：

pIShell | 指向 IShell 对象的指针
pBuff | 要填入字符串的缓冲区
nSize | 输入缓冲区大小（字节）

返回值：

填入的字节数。

如果没有找到版权字符串或缓冲区 pBuff 为 NULL，则返回 0

备注：

无

另请参阅：

无

返回函数列表

ISHELL_GetAppPrefs()

说明：

此方法提供了一种获取包含小程序首选项的结构的方法。 应用程序可以使用这种方法，不断保存/获取应用程序特定的设置或首选项信息。 这些信息将保存在文件中， 使用 ISHELL_SetAppPrefs() 可保存这些首选项。

原型：

int ISHELL_GetAppPrefs
(
IShell * pIShell,
uint16 wVer,
void * pCfg,
uint16 nSize
)

参数：

pIShell | 指向 IShell 对象的指针
wVer | 首选项版本
pCfg | 使用首选项数据填写的内存的指针
nSize | 要填写的内存块的大小

返回值：

如果操作成功，则返回 SUCCESS。

如果 pCfg == NULL 或 nSize 不足，则返回记录的非零大小

备注：

无

另请参阅：

ISHELL_SetAppPrefs()

返回函数列表

ISHELL_GetAppVersion()

说明：

此方法允许调用程序检索活动小程序的版本字符串。 这些信息可以从 MIF 中获取。

原型：

int ISHELL_GetAppVersion(IShell * pIShell, AECHAR * pBuff, int nSize);

参数：

pIShell | 指向 IShell 对象的指针
pBuff | 要填入字符串的缓冲区
nSize | 输入缓冲区大小（字节）

返回值：

填入的字节数。

如果没有找到版本字符串或缓冲区 pBuff 为 NULL，则返回 0

备注：

无

另请参阅：

无

返回函数列表

ISHELL_GetDeviceInfo()

说明：

此函数用于查询 AEE 外壳以获取有关设备性能的信息，例如所支持的 RAM 容量、
屏幕显示及其它项目。 要获取 AEEDeviceInfo 结构的 dwNetLinger 和 dwSleepDefer 值，则在调用此函数之前，wStructSize 必须等于 sizeof(AEEDeviceInfo)。 例如：

AEEDeviceInfo di;
di.wStructSize = sizeof(AEEDeviceInfo);
ISHELL_GetDeviceInfo(pIShell, &di);

原型：

void ISHELL_GetDeviceInfo(IShell * pIShell, AEEDeviceInfo * pi)

参数：

pIShell | 指向 IShell 接口对象的指针。
pi | 指向要填充的 AEEDeviceInfo 结构的指针。

返回值：

无

备注：

无

另请参阅：

AEEDeviceInfo

返回函数列表

ISHELL_GetDeviceInfoEx()

说明：

此方法用于获取有关设备的特定信息。 该函数使用 ID 指定所需信息， 返回时在缓冲区中包含对应的信息。

原型：

int ISHELL_GetDeviceInfoEx
(
IShell *pIShell,
AEEDeviceItem nItem,
void *pBuff,
int *pnSize
);

参数：

pIShell | 指向 IShell 接口对象的指针
nItem | 指定需要其信息的项目。 有关支持的设备项目，请参阅 AEEDeviceItem 文档。
pBuff | 返回时包含对应信息；如果查询项目的大小，则可能返回 NULL。
pnSize | 包含 pBuff 的大小。 返回时，则包含已填充的大小。

返回值：

如果成功，则返回 SUCCESS。

EBADPARM： 如果传递了错误的参数

EUNSUPPORTED，如果不支持该项目

备注：

无

另请参阅：

AEEDeviceItem

返回函数列表

ISHELL_GetHandler()

说明：

此函数用于对已注册内容查看器和协议模式处理程序的 AEE 外壳数据库进行查询访问。 该数据库允许浏览器和内容查看器显露所支持内容或数据协议的处理程序。

AEEHandlerType 数据结构用于指示输入字符串为查看器（如图像类型）还是声音
类型。

原型：

AEECLSID ISHELL_GetHandler
(
IShell * pIShell,
AEECLSID clsBase,
const char * pszIn
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsBase | 处理程序类型（HTYPE_VIEWER、HTYPE_SOUND）或处理程序符合的 AEECLSID 基类。
pszIn | 输入字符串。

返回值：

相关处理程序类的 AEECLSID。

否则，返回 0（零）。

备注：

无

另请参阅：

AEECLSID 列表

AEEHandlerType

ISHELL_RegisterHandler()

返回函数列表

ISHELL_GetItemStyle()

说明：

此函数用于向 AEE 外壳查询有关菜单、图标和列表项的默认样式信息。 这些信息将保存在两个指定的指针中： 第一个指针 pNormal 包含正常情况下（未选取）绘制项目的信息。 第二个指针 pSel 包含在选取情况下绘制项目的信息。

原型：

void ISHELL_GetItemStyle
(
IShell * pIShell,
AEEItemType t,
AEEItemStyle * pNormal,
AEEItemStyle * pSel
)

参数：

pIShell | [in] | 指向 IShell 接口对象的指针。
t | [in] | 项目类型。
pNormal | [out] | 指向将填充未选项信息的 AEEItemStyle 的指针。
pSel | [out] | 指向将填充已选项信息的 AEEItemStyle 的指针。

返回值：

无

备注：

无

另请参阅：

AEEItemType

AEEItemStyle

返回函数列表

ISHELL_GetJulianDate()

说明：

此函数用于根据输入的秒值填充 JulianType 数据结构。 该值表示从 1980 年 1 月 6 日 00:00:00 GMT（设备参考时间）起至今的秒数。 如果输入值为 0（零），则返回当前的系统时间。

原型：

void ISHELL_GetJulianDate
(
IShell * pIShell,
uint32 dwSecs,
JulianType * pDate
)

参数：

pIShell | 指向 IShell 接口对象的指针。
dwSecs | 从 1980 年 1 月 6 日（设备的参考时间）起至今的秒数。
pDate | 指向返回时需要填充的结构的指针。

返回值：

无

备注：

在 Windows 中，dwSecs 的上限是设备参考时间 1980 年 1 月 6 日 00:00:00 GMT 和 PC 参考时间 1970 年 1 月 1 日 00:00:00 GMT 之差与 uint32 所允许最大值之间的差额。

另请参阅：

JulianType

GETJULIANDATE()

ISHELL_GetSeconds()

ISHELL_GetTimeMS()

ISHELL_GetUpTimeMS()

GET_SECONDS()

GET_TIMEMS()

ISHELL_GetUpTimeMS()

GETTIMESECONDS()

GETTIMEMS()

返回函数列表

ISHELL_GetPosition()

建议不使用此方法。 请使用 IPOSDET_GetGPSInfo() 获取基于 GPS 的位置信息。

说明：

建议不使用此方法。 请使用 IPOSDET_GetGPSInfo 获取基于 GPS 的位置信息。
使用此接口需要定位权限。 该方法提供对手机 gpsOne 定位功能的访问。 指定的精度值指示返回的精确定位程度， 同时也与满足请求需要的时间直接相关。

注意：OEM 或运营商确定的保密策略将保护定位请求。 完成后，回调将向用户提供位置或适当的错误信息。

原型：

int ISHELL_GetPosition
(
IShell * pIShell,
AEEPosAccuracy prc,
PFNPOSITIONCB pfn,
void * pUser
)

参数：

pIShell | 指向 IShell 接口对象的指针。
prc | 精度。
pfn | 指向回调的指针。
pUser | 指向回调数据的指针。

返回值：

如果调用在进行中，则返回 SUCCESS。

如果不支持 GPS，则返回 EUNSUPPORTED。

如果无法获取 GPS 信息，则返回 EFAILED。

如果应用程序没有需要的权限，则返回 EPRIVLEVEL。

备注：

有关 SDK 中 GPS 模拟的详细信息，请参阅 IPosDet 接口文档，以及SDK 用户指南 和 实用程序指南。

另请参阅：

IPosDet 接口

AEEPosAccuracy

PFNPOSITIONCB

返回函数列表

ISHELL_GetPrefs()

说明：

此函数提供了获取包含小程序或类级别首选项的结构的方法。

原型：

int ISHELL_GetPrefs
(
Shell * pIShell,
AEECLSID cls,
uint16 wVer,
void * pCfg,
uint16 nSize
)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 首选项类型的 AEECLSID。
wVer | 首选项版本。
pCfg | 指向使用首选项数据填充的内存的指针。
nSize | 要填充的内存块的大小。

返回值：

如果操作成功，则返回 SUCCESS。

如果 pCfg == NULL 或 nSize 不足，则返回记录的非零大小

如果操作失败，则返回 EFAILED。

备注：

无

另请参阅：

AEECLSID 列表

ISHELL_SetPrefs()

返回函数列表

ISHELL_GetRand()

注意：建议不使用此函数， 而使用助手函数 GETRAND()。

说明：

此函数可以使用设备上的随机数发生器， 并用随机值数组填充输入缓冲区。

原型：

void ISHELL_GetRand(IShell * pIShell, byte * pDest, int nSize)

参数：

pIShell | 指向 IShell 接口对象的指针。
pDest | 目标缓冲区。
nSize | 缓冲区的大小（字节）。

返回值：

无

备注：

此函数使用设备的随机数发生器，向输入缓冲区填充一系列随机字节。 该序列会在当前时间形成种子值，所以，除非间隔至少几毫秒，否则多次调用会得到相同的结果。 要获得最佳结果，可在每次调用事件处理程序函数时调用一次该函数。

另请参阅：

GETRAND()

返回函数列表

ISHELL_GetResSize()

说明：

此函数是 ISHELL_LoadResDataEx() 的包装。 它用于计算已找到资源的大小，如果未找到资源，则为返回 0。

原型：

uint32 ISHELL_GetResSize
(
IShell * pIShell,
const char * pszResFile,
uint16 nResID,
ResType nType,
uint32 *pnBufSize
);

参数：

pIShell
指向 IShell 对象的指针
pszResFile
包含数据的资源文件
nResID
资源文件中的数据 ID
nType
资源类型
  • [RESTYPE_STRING|RESTYPE_IMAGE|RESTYPE_DIALOG| RESTYPE_CONTROL|RESTYPE_LISTITEM|RESTYPE_BINARY]
pnBufSize
可以不为 null

返回值：

如果失败，则返回 0

如果成功，则返回资源大小。

备注：

无

另请参阅：

ISHELL_LoadResDataEx()

返回函数列表

ISHELL_GetSeconds()

注意：建议不使用此函数， 而使用助手函数 GETTIMESECONDS()。

说明：

此函数用于返回从 1980 年 1 月 6 日 00:00:00 GMT 至今的秒数
（已调整为当地时间）。

原型：

uint32 ISHELL_GetSeconds(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

1980 年 1 月 6 日 00:00:00 GMT 至今经过的秒数。

备注：

无

另请参阅：

ISHELL_GetTimeMS()

ISHELL_GetJulianDate()

ISHELL_GetUpTimeMS()

返回函数列表

ISHELL_GetTimeMS()

说明：

此函数用于返回当前时间（毫秒）。 返回的值取决于 BREW 移动设备从基站获取的设备当前时间值。 当设备首次获取系统覆盖范围时，该值可能会有较大的变化。

原型：

uint32 ISHELL_GetTimeMS(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

从午夜开始经过的时间（毫秒数）。

备注：

无

另请参阅：

ISHELL_GetUpTimeMS()

ISHELL_GetJulianDate()

ISHELL_GetSeconds()

返回函数列表

ISHELL_GetTimerExpiration()

说明：

此函数用于返回与设备用户回调或数据相关联的计时器过期前剩余的时间（毫秒）。

原型：

uint32 ISHELL_GetTimerExpiration
(
IShell * pIShell,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pfn | 用户回调。
pUser | 用户数据。

返回值：

如果与指定的设备用户回调或数据相关联的计时器尚未过期，则此函数将返回到期前剩余的时间。

否则，返回 0（零）。

备注：

无

另请参阅：

PFNNOTIFY

ISHELL_SetTimer()

ISHELL_CancelTimer()

返回函数列表

ISHELL_GetUpTimeMS()

说明：

此函数用于返回设备开机后经过的时间（毫秒）。 它与 ISHELL_GetTimeMS() 不同，其返回值不会因初次获取系统覆盖范围而发生较大的变化。

原型：

uint32 ISHELL_GetUpTimeMS(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

设备开机后经过的时间（毫秒数）。

备注：

无

另请参阅：

ISHELL_GetTimeMS()

ISHELL_GetSeconds()

ISHELL_GetJulianDate()

返回函数列表

ISHELL_HandleEvent()

说明：

此函数用于将一种指定的标准 AEE 事件 发送到当前激活的小程序。 它会内部调用 ISHELL_SendEvent()，并将 ClassID 设置为 0（零）。 此函数只能发送以下范围内的事件： EVT_COMMAND 到 EVT_USER。 它不能发送等于或大于 EVT_USER 的事件。 此函数只能用于用户实现的控件。 例如，如果控件要将事件 EVT_CTL_TAB 发送到当前活动的应用程序，则可以使用此函数。 通常，应用程序必须使用函数 ISHELL_SendEvent() 或 ISHELL_PostEvent() 来将事件发送到其本身或其它指定的应用程序。

原型：

boolean ISHELL_HandleEvent
(
IShell * pIShell,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIShell | 指向 IShell 接口对象的指针。
evt | AEE 事件.
wp | 事件特定的 16 位值。
dwp | 事件特定的 32 位值。

返回值：

如果已处理事件，则返回 TRUE。

如果尚未处理事件，则返回 FALSE。

备注：

发送的事件必须为标准 AEE 事件之一。 例如，它必须小于 EVT_USER；而不能为 EVT_USER 事件。 使用 ISHELL_PostEvent() 可发送用户事件。

另请参阅：

ISHELL_SendEvent()

ISHELL_PostEvent()

返回函数列表

ISHELL_IsValidResource()

说明：

此函数用于检验指定的资源文件项对于指定的类型是否有效。

原型：

boolean ISHELL_IsValidResource
(
IShell * pIShell,
const char * pszResFile,
uint16 wID,
ResType t,
AEEHandlerType ht
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 资源文件名。
wID | 资源 ID。
t | 资源类型。
ht | 处理程序类型（如果 t != RESTYPE_IMAGE，则忽略）。

返回值：

如果文件中存在资源，则返回 TRUE。

如果资源不存在，则返回 FALSE。

另请参阅：

ResType

AEEHandlerType

返回函数列表

ISHELL_LoadBitmap()

说明：

此函数用于直接加载位图文件，并返回位图的 IBitmap * 处理程序。

原型：

IBitmap * ISHELL_LoadBitmap(IShell * pIShell, const char * pszFile)

参数：

pIShell | 指向 IShell 接口对象的指针
pszFile | 图像文件

返回值：

指向 IBitmap 接口的指针。

备注：

它是一个“宏”

另请参阅：

ISHELL_LoadResBitmap()

返回函数列表

ISHELL_LoadBusyImage()

说明：

此方法用于加载指示 BREW 正忙的图像。 该图像是一个沙漏， 应用程序忙于执行某操作时，可以在屏幕上显示此图像。

原型：

IImage *IShell_LoadBusyImage(IShell *pIShell)

参数：

pIShell
指向 IShell 对象的指针

返回值：

如果成功，则返回 IImage 指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

无

返回函数列表

ISHELL_LoadImage()

说明：

此函数可以从文件直接加载图像，并返回用于显示图像的 IImage 处理程序的指针。

原型：

IImage * ISHELL_LoadImage(IShell * pIShell, const char * pszImageFile)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszImageFile | 图像文件。

返回值：

指向用于查看图像的 IShell 接口的指针。

备注：

示例：

IImage * pImage;
pImage = ISHELL_LoadImage(pShell, “Test.bmp”);
If (IImage)
{
IIMAGE_draw(pImage, 10,70);
IIMAGE_Release(pImage);
}

另请参阅：

ISHELL_LoadResData()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_LoadSound()

ISHELL_FreeResData()

返回函数列表

ISHELL_LoadResBitmap()

说明：

此函数用于从给定的资源文件中加载位图资源，并返回有效的 IBitmap 接口指针。

原型：

ISHELL_LoadResBitmap(p,psz,id)

参数：

PIshell | 指向 Ishell 接口对象的指针
psz | 包含位图的资源文件
ID | 资源文件中的位图 ID

返回值

如果成功，则返回指向 IBitmap 接口（图像）的指针。

如果失败，则返回 NULL。

备注：

它是一个 ISHELL_LoadResObject() 的相关“宏”。

另请参阅：

ISHELL_LoadBitmap()

返回函数列表

ISHELL_LoadResData()

说明：

此函数用于返回与指定资源文件、ID 及类型相关联的 void * 数据块。 返回的内存必须使用 ISHELL_FreeResData() 释放。

原型：

void * ISHELL_LoadResData
(
IShell * pIShell,
const char * pszResFile,
int16 nResID,
ResType nType
)

参数：

pIShell
指向 IShell 接口对象的指针。
pszResFile
包含数据的资源文件。
nResID
资源文件中的数据 ID。
nType
资源类型：
  • RESTYPE_IMAGE，
  • RESTYPE_DIALOG，
  • RESTYPE_CONTROL，
  • RESTYPE_ LISTITEM，
  • RESTYPE_BINARY
如果 nType 为 RESTYPE_IMAGE，则第一个字节指示实际图像数据开始处的偏移量，第二个字节为 0（零）。 从第三个字节开始，字符串指示 MIME 类型，随后是实际图像数据。

返回值：

如果成功，则返回指向资源数据的空指针。

否则，返回 NULL。

备注：

调用 ISHELL_LoadResString() 可加载字符串。

另请参阅：

ResType

ISHELL_LoadImage()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_LoadSound()

ISHELL_FreeResData()

返回函数列表

ISHELL_LoadResDataEx()

说明：

此函数尝试加载指定资源环境中由类型和 ID 指定的资源。 此函数可以分配内存，或将资源加载到预分配的缓冲区中。 如果该函数分配内存，则必须使用 ISHELL_FreeResData() 将其释放。

原型：

void *ISHELL_LoadResDataEx
(
IShell * pIShell,
const char * pszResFile,
uint16 nResID,
ResType nType,
void * pBuf,
uint32 * pnBufSize
)

参数：

pIShell
指向 IShell 对象的指针。
pszResFile
包含数据的资源文件。
nResID
资源文件中的数据 ID。
nType
资源类型：
  • RESTYPE_STRING，
  • RESTYPE_IMAGE，
  • RESTYPE_DIALOG，
  • RESTYPE_CONTROL，
  • RESTYPE_LISTITEM，
  • RESTYPE_BINARY
pBuf
加载资源数据的缓冲区。

如果 pBuf 为 NULL，则已分配缓冲区来保存加载的资源，
且必须使用 ISHELL_FreeResData() 将其释放。

如果 pBuf 为 -1，则未分缓冲区，但已计算大小信息并在 pnBufSize 中返回。

pnBufSize
不能为 NULL。
[in]
如果 pBuf 不为 NULL 或 -1，则“输入”时指向 sizeof(pBuf)（字节）。
如果 pBuf 为 NULL 或 -1，则“输入”时忽略 pnBufSize。
[out]
包含读取的资源数据大小。
如果“输入”时 pBuf 不为 NULL，而 *pnBufSize 因太小而无法保存资源，
或者如果 pBuf 为 -1，则将实际的资源大小填入 pnBufSize。
在后两种情况下，该函数将返回 NULL。

返回值：

如果成功，则返回指向资源数据的空指针。

如果加载资源失败或因缓冲区大小太小而无法保存资源，则返回 NULL。

备注：

如果加载字符串资源，则 pBuf 的内容（和返回的 void *）为该字符串字节
（不包括 NULL 终结符）。 如果加载图像资源，则 pBuf 的内容为一个 AEEResBlob 结构，
其原始数据位于 RESBLOB_DATA(pBuf)。

另请参阅：

ISHELL_FreeResData()

AEEResBlob

返回函数列表

ISHELL_LoadResImage()

说明：

此函数用于从给定的资源文件加载位图资源，并返回有效的 IImage 接口指针。
返回的指针可用于查看图像。

原型：

IImage * ISHELL_LoadResImage
(
IShell * pIShell,
const char * pszResFile,
int16 nResID
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 包含位图图像的资源文件。
nResID | 资源文件中位图的 ID。

返回值：

如果成功，则返回用于查看图像的 IImage 接口指针。

如果失败，则返回 NULL。

备注：

此函数使用 SHELL_LoadResObject。

另请参阅：

ISHELL_LoadImage()

ISHELL_LoadResData()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_LoadSound()

ISHELL_FreeResData()

返回函数列表

ISHELL_LoadResObject()

说明：

此函数用于加载指定的资源，并创建可用于该资源数据的处理程序。 hType 指示创建的处理程序类型。

原型：

IBase * ISHELL_LoadResObject
(
IShell * pIShell,
const char * pszResFile,
int16 nResID,
AEEHandlerType hType
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 包含指定资源的资源文件。
nResID | 资源文件中的资源 ID。
hType | 必须创建且与资源数据相关联的处理程序类型。 此函数返回的接口指针取决于指定的处理程序类型。 AEEHandlerType 必须与资源数据的实际类型一致。

返回值：

如果成功，则返回处理资源数据的指针。

如果失败，则返回 NULL。

备注：

例如：

如果资源数据的类型是 HTYPE_SOUND，并且 hType 参数的值是 HTYPE_VIEWER，则将无法预测此函数的行为。

如果 hType 为 HTYPE_VIEWER，则指示资源数据是位图资源。 此函数将创建一个 IImage 接口，并将资源数据与其关联， 然后，返回 IImage 接口指针。
该接口指针可用于查看图像。

如果 hType 为 HTYPE_SOUND，则指示资源数据是声音流。 这时，函数将创建并返回可以播放声音的 ISoundPlayer 接口指针。

ISHELL_LoadResImage() 和 ISHELL_LoadResSound() 是此函数的特例，其中 hType 参数分别设置为 HTYPE_VIEWER 和 HTYPE_SOUND。

另请参阅：

ISHELL_LoadImage()

ISHELL_LoadResData()

ISHELL_LoadResImage()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_LoadSound()

ISHELL_FreeResData()

返回函数列表

ISHELL_LoadResSound()

说明：

当声音数据作为原始字节流包含在资源文件中时，可以使用此函数。 该函数用于从给定的资源文件加载原始声音缓冲区，它创建 ISoundPlayer 接口指针，并以 SDT_BUFFER 作为 AEESoundPlayerInput 数据参数来调用 ISOUNDPLAYER_Set()，将声音数据设置到该接口。 这时即可使用 ISoundPlayer 接口指针播放声音。

注意：此函数从 BREW 资源文件中读取声音资源。 因为当前版本 BREW 中的
BREW 资源编辑器不支持声音资源，所以不支持此函数。

原型：

ISoundPlayer * ISHELL_LoadResSound
(
IShell * pIShell,
const char * pszResFile,
int16 nResID
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 包含原始声音数据的资源文件。
nResID | 原始声音数据的 ID。

返回值：

如果成功，则返回用于播放声音的 ISoundPlayer 接口指针。

如果失败，则返回 NULL。

备注：

该函数使用 ISHELL_LoadResObject()。

另请参阅：

ISHELL_LoadImage()

ISHELL_LoadResData()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResString()

ISHELL_LoadSound()

返回函数列表

ISHELL_LoadResString()

说明：

此函数允许调用程序获取保存在指定资源文件中的 UNICODE 或 ISOLATIN 字符串。 返回的字符串将放置在提供的缓冲区中。

原型：

int ISHELL_LoadResString
(
IShell * pIShell,
const char * pszResFile,
int16 nResID,
AECHAR * pBuff,
int nSize
)

参数：

pIShell | [in] | 指向 IShell 接口对象的指针。
pszResFile | [in] | 包含字符串的资源文件。
nResID | [in] | 资源文件中的字符串 ID。
pBuff | [out] | 要填充字符串的缓冲区。
nSize, | [in] | 输入缓冲区的大小（字节）。

返回值：

如果成功，则返回填充的字符数。

否则，返回 0（零）。

备注：

无

另请参阅：

ISHELL_LoadImage()

ISHELL_LoadResData()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadSound()

返回函数列表

ISHELL_LoadSound()

说明：

此函数用于从文件系统加载声音文件，并返回该文件的 ISoundPlayer 接口对象。

原型：

ISoundPlayer * ISHELL_LoadSound
(
IShell * pIShell,
const char * pszResFile
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 声音文件。

返回值：

如果成功，则返回用于播放声音的 ISoundPlayer 接口指针。

否则，返回 NULL。

备注：

该函数使用 ISHELL_LoadResObject()。

另请参阅：

ISHELL_LoadImage()

ISHELL_LoadResData()

ISHELL_LoadResImage()

ISHELL_LoadResObject()

ISHELL_LoadResSound()

ISHELL_LoadResString()

ISHELL_FreeResData()

返回函数列表

ISHELL_MessageBox()

说明：

此函数用于指示 AEE 外壳向设备用户显示消息框。 消息框是具有标题和文本的简单窗口。 设备用户可使用 END 或 CLR 键将其清除。 标题和文本从指定资源文件获取。

原型：

boolean ISHELL_MessageBox
(
IShell * pIShell,
const char * pszResFile,
uint16 wTitleID,
uint16 wTextID
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pszResFile | 包含标题和文本的资源文件。 如果为 NULL，则将使用文本 （如，wTextID）资源 ID 从语言目录（例如 "en" 表示英语）下的 BREW 资源文件 (AEEControls.bar) 中获取错误消息， 然后将该错误消息显示在消息框中。
wTitleID | 标题 ID，最多 128 字节（64 个 UNICODE 字符）。
wTextID | 文本 ID，最多 256 字节（128 个 UNICODE 字符）。

返回值：

如果已创建消息框，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

ISHELL_MessageBoxText()

返回函数列表

ISHELL_MessageBoxText()

说明：

此函数用于指示 AEE 外壳向设备用户显示消息框。 消息框是具有标题和文本的简单窗口。 设备用户可使用 END 或 CLR 键将其清除。 与 ISHELL_MessageBox() 不同，
此函数使用提供的标题和文本字符串。

原型：

boolean ISHELL_MessageBoxText
(
IShell * pIShell,
const AECHAR * pTitle,
const AECHAR * pText
)

参数：

pIShell | 指向 IShell 接口对象的指针。
pTitle | 指向标题字符串的指针。
pText | 指向文本字符串的指针。

返回值：

如果成功，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

ISHELL_MessageBox()

返回函数列表

ISHELL_Notify()

说明：

如果对象检测到可能与其它对象类请求的通知相关联的事件，则将调用此函数。 例如，在发生 INetMgr 相关事件时，INetMgr 接口将调用此函数。 这样，任何请求通知的小程序，无论是否已加载激活，都会收到 EVT_NOTIFY，其中包含与特定事件有关的数据。 通知掩码用于指示发生的事件。 所提供的数据指针特定于发生事件的掩码，并由触发通知的类定义。 所有注册以接收特定类型通知的小程序将被调用。 如果小程序当前不处于激活状态，则会加载小程序，并向其发送事件。 这时，不会发送 EVT_APP_START 或 EVT_APP_STOP 事件。 如果小程序基于事件启动，则必须调用 ISHELL_StartApplet()。

原型：

void ISHELL_Notify
(
IShell * pIShell,
AEECLSID clsType,
uint32 dwMask,
void * pData
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsType | 发出通知的类。
dwMask | 事件掩码，其中对于任意给定事件，通常仅设置一位。
pData | 上下文相关数据。

返回值：

如果成功，则返回 SUCCESS。

如果 ClassID 无效，则返回 EBADCLASS。

如果参数无效，则返回 EBADPARM。

如果内存不足，则返回 ENOMEMORY。

如果尝试重新开始 ISHELL_Notify()，则返回 EREENTERED。

如果无效任务发布通知，则返回 EBADTASK。

备注：

无

另请参阅：

ISHELL_RegisterNotify()

返回函数列表

ISHELL_OnAppClose()

说明：

此函数用于启用小程序，以注册在关闭小程序时调用的系统回调。

原型：

void ISHELL_OnAppClose(IShell * pIShell, AEECallback * pcb);

参数：

pIShell | 指向 IShell 对象的指针
pcb | 指向回调的指针

返回值：

无

备注：

无

另请参阅：

AEECallback

返回函数列表

ISHELL_OnExit()

说明：

此函数用于启用小程序，以注册在退出 BREW 时要调用的系统回调。

原型：

void ISHELL_OnExit(IShell * pIShell, AEECallback * pcb);

参数：

pIShell | 指向 IShell 对象的指针
pcb | 指向回调的指针

返回值：

无

备注：

无

另请参阅：

AEECallback

返回函数列表

ISHELL_OnInit()

说明：

此方法用于注册初始化 BREW 时要调用的回调。 如果调用此函数时已经初始化 BREW，则立即调用回调。

原型：

void ISHELL_SetOnInit(IShell * pIShell, AEECallback * pcb);

参数：

pIShell： 指向 IShell 对象的指针

pcb： 要调用的回调

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ISHELL_OnLowRAM()

说明：

此方法用于注册在系统内存不足时要调用的回调。 这允许应用程序进行内存清理，
以释放更多系统内存。

原型：

void ISHELL_SetOnLowRAM(IShell * pIShell, AEECallback * pcb);

参数：

pIShell： 指向 IShell 对象的指针

pcb： 要调用的回调

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ISHELL_OnLowStorage()

说明：

此方法用于注册在文件系统空间不足时要调用的回调。 这允许应用程序进行文件系统清理，以释放更多的文件系统空间。

原型：

void ISHELL_SetOnLowStorage(IShell * pIShell, AEECallback * pcb);

参数：

pIShell： 指向 IShell 对象的指针

pcb： 要调用的回调

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ISHELL_OnModUnload()

说明：

此函数允许客户端注册要卸载模块时调用的回调。

原型：

void ISHELL_OnModUnload(IShell * pIShell, AEECallback * pcb);

参数：

pIShell | 指向 IShell 对象的指针
pcb | 指向 AEECallback 结构的指针

返回值：

无

备注：

该回调必须由客户端来分配。

另请参阅：

ISHELL_RegisterSystemCallback()

返回函数列表

ISHELL_PostEvent()

说明：

此函数用于向指定的小程序传递异步事件。 该函数与 ISHELL_SendEvent() 相似，
主要的不同之处在于，它可以将事件传递给小程序，而ISHELL_SendEvent() 则是直接向小程序发送事件。 事件传递适用于特殊的情况，例如调用程序传递其它任务的事件，或者将事件处理延迟到下一个事件循环。 在处理其它事件的同时保持程序不间断执行方面，此函数非常有用。 通过定义 EVT_USER 级别或超出该级别的事件，并指定小程序 ClassID，可以向小程序发送私有事件。 如果发送 EVT_USER 范围和超出该范围的事件却没有相关联的 ClassID，则将返回错误。

原型：

boolean ISHELL_PostEvent
(
IShell * pIShell,
AEECLSID clsApp,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsApp | 接收事件的小程序的 ClassID。 该参数必须存在并指定小程序。 如果此处指定的 clsApp 不属于小程序，此函数仍可返回 TRUE；但是，当事件弹出队列，并尝试将其发送给 clsApp 指定的小程序时，实际发送将失败。
evt | AEE 事件.
wp | 事件特定的 16 位值。
dwp | 事件特定的 32 位值。

返回值：

如果事件已传递，则返回 TRUE。 返回状态仅指示事件是否已成功地放置在队列中， 而并不指示事件是否已成功地发送给接收小程序。

如果尚未传递事件，则返回 FALSE。

备注：

无

另请参阅：

AEECLSID 列表

AEE 事件

ISHELL_SendEvent()

返回函数列表

ISHELL_Prompt()

说明：

此函数可以为应用程序提供显示多项选择提示的机制。 文本可从资源文件指定或直接通过 AEEPromptInfo 数据结构传入。 在尝试从资源文件加载文本以前，AEE 外壳将首先检查文本指针。 按钮由 AEEPromptInfo->pBtnIDs 列表中的值指定。 为了方便起见，假定按钮的 ID 与该按钮的文本和命令 ID 相关联。 如果传递的按钮指针为 NULL，则会成功显示该提示，但没有任何按钮。 当设备用户选择按钮或按下 CLR 键时，提示对话框将自动清除。 这种情况下，将向应用程序发送 EVT_COMMAND 消息，其中的 16 位附加参数用于指示选择的 ID。

原型：

boolean ISHELL_Prompt(IShell * pIShell, AEEPromptInfo * pi)

参数：

pIShell | 指向 IShell 接口对象的指针。
pi | 指向 AEEPromptInfo 数据结构的指针。

返回值：

如果已创建提示，则返回 TRUE。

如果没有创建提示，则返回 FALSE。

备注：

在实例化提示时，pBtnIDs 数组中的第一个按钮将始终处于选中（突出显示）状态。

另请参阅：

AEEPromptInfo

返回函数列表

ISHELL_QueryClass()

说明：

此函数用于查询 AEE 外壳，以确定是否支持指定的类或小程序。 如果提供了 AEEAppInfo 数据结构指针，AEE 外壳将假定所请求的类为小程序。 这种情况下，
如果找到所请求的小程序类，将填充该结构。 如果支持该类，但它不是小程序，此函数将返回 FALSE。 如果没有传递 AEEAppInfo 指针，AEE 外壳将假定该请求用于检查类的可用性，而不管它是否为小程序。 此函数还将检查请求程序是否具有创建请求的类所需的权限。 如果请求程序不具备此权限，即使实际系统中有可用类，函数也将返回 FALSE。

原型：

boolean ISHELL_QueryClass
(
IShell * pIShell,
AEECLSID cls,
AEEAppInfo * pai
)

参数：

pIShell | in] | 指向 IShell 接口对象的指针。
cls | [in] | 请求的接口的 32 位 ClassID。
pai | [out] | 指向将填充小程序信息的 AEEAppInfo 结构的指针。

返回值

如果支持类，则返回 TRUE。

如果不支持类，则返回 FALSE。

备注：

如果提供了 AEEAppInfo，而所请求的类可用但不是小程序，则函数将返回 FALSE。

另请参阅：

AEEAppInfo

ISHELL_CreateInstance()

返回函数列表

ISHELL_RegisterHandler()

说明：

此函数可以为内容查看器或协议引擎提供向 AEE 外壳注册自身的机制。 这样在遇到内容或协议类型时，其它组件可以共享该函数的功能。 由于处理程序由类指定，因此可以根据需要动态加载。 要更新处理程序，必须通过使用 0（零）ClassID 参数调用 ISHELL_RegisterHandler()，从数据库中删除现有的处理程序。

原型：

int ISHELL_RegisterHandler
(
IShell * pIShell,
AEECLSID clsBase,
const char * pszIn,
AEECLSID cls
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsBase | 处理程序类型（HTYPE_VIEWER、HTYPE_SOUND）基类。
pszIn | 输入字符串。 如果为 NULL，则返回 EBADPARM。 该字符串包含用逗号分隔的 MIME 类型列表或由指定类处理的模式列表。
cls | 处理程序的 AEECLSID。 不对此参数执行验证。

返回值：

如果操作成功，则返回 SUCCESS。

如果 ClassID 无效，则返回 EBADCLASS。

如果参数无效，则返回 EBADPARM。

如果内存不足，则返回 ENOMEMORY。

如果操作失败，则返回 EFAILED。

如果处理程序已设置，则返回 EALREADY。

备注：

无

另请参阅：

AEECLSID 列表

AEEHandlerType

ISHELL_GetHandler()

返回函数列表

ISHELL_RegisterNotify()

说明：

此函数用于提供一种机制，使小程序注册接收从其它类发出的通知。 例如，小程序可以注册接收来自 AEECLSID_NET 接口中特定于该类的事件通知。 通知掩码用于指示与调用程序相关的事件类型。 这些位根据每个类进行定义，允许类定义和共享通知，而不要求 IShell 接口定义所有这些通知。

指定的通知掩码将被明确使用， 其值不与现有的通知掩码（如果有）做“或”运算。 当请求特定对象类的通知时，将创建该对象类或者增加其引用计数。 删除通知时
（掩码=0），则减少该对象的引用计数。

要注销所有的通知，请将 dwMask 设置为 0，调用此函数。

原型：

int ISHELL_RegisterNotify
(
IShell * pIShell,
AEECLSID clsNotify,
AEECLSID clsType,
uint32 dwMask
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsNotify | 事件发生时，要创建和通知的小程序。
clsType | 发出事件的类。 它是通知程序类，必须实现 INotifier 接口函数。
dwMask | 要触发事件的掩码。 将其设置为零将导致调用程序注销通知程序类中的所有通知。

返回值：

如果成功，则返回 SUCCESS。

如果 ClassID 无效，则返回 EBADCLASS。

如果参数无效，则返回 EBADPARM。

如果内存不足，则返回 ENOMEMORY。

备注：

无

另请参阅：

AEECLSID 列表

ISHELL_Notify()

INOTIFIER_SetMask()

返回函数列表

ISHELL_RegisterSystemCallback()

说明：

此函数允许客户端为重要的系统事件注册回调，如： 启动 BREW 时、退出应用程序时、卸载模块时等。

原型：

void ISHELL_RegisterSystemCallback
(
IShell * pIShell,
AEECallback * pcb,
int nSCBType
);

参数：

pIShell | 指向 IShell 对象的指针
pcb | 指向 AEECallback 结构的指针
nSCBType | 注册的系统回调类型

返回值：

无

备注：

该回调必须由客户端来分配。

以下为可能 nSCBType 值：

AEE_SCB_AEE_INIT： 初始化 BREW 时调用

AEE_SCB_AEE_EXIT： 退出 BREW 时调用

AEE_SCB_LOW_RAM： 设备 RAM 低于预设阈值时调用

AEE_SCB_LOW_STORAGE： 设备存储空间低于预设阈值时调用

AEE_SCB_APP_CLOSED： 要关闭应用程序时调用

AEE_SCB_MOD_UNLOAD： 要卸载模块时调用

另请参阅：

ISHELL_OnInit()

ISHELL_OnLowRAM()

ISHELL_OnLowStorage()

ISHELL_OnModUnload()

返回函数列表

ISHELL_Release()

说明：

此函数用于减少 IShell 接口对象的引用计数。 引用计数为 0（零）时，将从内存中释放该对象且不再有效。

原型：

uint32 ISHELL_Release(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

已减少的对象引用计数。

如果已释放对象，且不再有效，则返回 0（零）。

备注：

此函数没有任何功能， AEE 将忽略该函数调用。

另请参阅：

ISHELL_AddRef()

返回函数列表

ISHELL_Resume()

说明：

此函数允许向 AEE 外壳注册回调。 它可以向 AEE 外壳的挂起操作列表中添加回调。 AEE 外壳将在下一次调用事件循环时调用此回调函数，以使应用程序或对象协同处理多任务。 如果该回调已注册，则需先将其注销，然后重新注册。

原型：

void ISHELL_Resume(IShell * pIShell, AEECallback * pcb)

参数：

pIShell
指向 IShell 接口对象的指针。
pcb
指向 AEECallback 结构的指针。 应用程序调用此函数时，调用程序必须设置 AEECallback 结构中的以下成员：
  • pfnNotify 成员必须由调用程序填充。 调用事件循环时，AEE 将调用此回调函数。
  • pNotifyData 必须由调用程序填充。 它是传递给回调函数的数据。
  • pfnCancel 成员必须在首次注册回调前由调用程序设置为 NULL。 函数返回时，AEE 外壳使用正确的值填充该成员。

返回值：

无

备注：

使用 ISHELL_Resume() 时，AEE 外壳将自动填写传递给它的 AEECallback 结构中的一些数据成员（例如，AEE 外壳将填写 pfnCancel 和 pCancelData 成员）。 要取消已注册的回调，请使用 AEECallback 结构的 pfnCancel 成员，并向它传递 pCancelData 参数。

示例：

AEECallback cb;
// 填写 cb 结构成员
cb.pfnNotify = MyCB;// 我的回调函数。 必须将其声明
// 为 void MyCB(void *)
cb.pNotifyData = pme;// 小程序特定数据
cb.pfnCancel = NULL;// 初始化为 NULL。 由外壳更新
// 执行以下代码注册回调：
ISHELL_Resume(myShellPtr,&cb);
// 执行以下代码取消 CB：
if(cb.pfnCancel)
cb.pfnCancel(&cb);

另请参阅：

AEECallback

返回函数列表

ISHELL_SendEvent()

说明：

完整的 AEE 执行模型基于半协作事件传递模型。 在此模型下，将使用 ISHELL_SendEvent() 向活动对话框或小程序发送事件，以控制目标小程序。 此函数可直接向目标小程序发送事件。 通过指定目标小程序，可以向特定的小程序发送事件。 如果小程序当前不在运行，则将加载小程序，并直接向它发送事件。 这时，小程序将在后台启动（不向小程序发送 EVT_APP_START 和 EVT_APP_STOP 事件）。 通过定义 EVT_USER 范围或超出该范围的事件，并指定小程序 ClassID，可以向小程序发送私有事件。 如果发送 EVT_USER 范围和超出该范围的事件而没有相关联的 ClassID，则将返回错误。 如果通过 EVT_USER 激活了对话框，则在向小程序传递事件之前，将先把事件传递给对话框。 仅在对话框不处理事件的情况下，才向小程序传递事件。 与事件相关联的 wp 和 dwp 参数是特定于事件的， AEE 外壳不检查这些值。

原型：

boolean ISHELL_SendEvent
(
IShell * pIShell,
AEECLSID clsApp,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pIShell | 指向 IShell 接口对象的指针。
clsApp | 接收事件的小程序类。 在 EVT_USER 范围内和超出该范围的事件需使用该参数。
evt | AEE 事件.
wp | 事件特定的 16 位值。
dwp | 事件特定的 32 位值。

返回值：

如果已处理事件，则返回 TRUE。

如果尚未处理该事件，则返回 FALSE。

备注：

无

另请参阅：

ISHELL_PostEvent()

返回函数列表

ISHELL_SetAlarm()

说明：

此函数允许调用程序为小程序设置长期警报。 警报到期时，将加载小程序并使用指定的 16 位 nUserCode 作为用户参数，向其传递 EVT_ALARM 事件。 发出警报时，如果小程序不处于激活状态，则将加载小程序但不会向其发送 EVT_APP_START 事件。 如果要激活小程序，则须调用 ISHELL_StartApplet()。 通过指定其它 16 位警报 nUserCode，可以为小程序设置多个警报。

原型：

int ISHELL_SetAlarm
(
IShell * pIShell,
AEECLSID cls,
uint16 nUserCode,
uint32 nMins
)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 警报到期时要调用的小程序类。
nUserCode | 传递给小程序的 16 位代码。
nMins | 从当前时间起设置警报的分钟数。

返回值：

如果成功，则返回 SUCCESS。

如果参数无效，则返回 EBADPARM。

如果内存不足，则返回 ENOMEMORY。

备注：

无

另请参阅：

ISHELL_CancelAlarm()

返回函数列表

ISHELL_SetAppPrefs()

说明：

此方法提供了一种方法以存储包含小程序特定首选项的结构。 应用程序可以使用这种方法，不断保存/获取应用程序特定的设置或首选项信息。 这些信息将保存在文件中。 使用 ISHELL_GetAppPrefs() 可获取首选项。

原型：

int ISHELL_SetPrefs
(
IShell * pIShell,
uint16 wVer,
void * pCfg,
uint16 nSize
)

参数：

pIShell | 指向 IShell 对象的指针
wVer | 首选项版本
pCfg | 指向要保存的首选项数据的指针
nSize | 要存储的内存块的大小

返回值：

SUCCESS 操作成功

备注：

无

另请参阅：

ISHELL_GetAppPrefs()

返回函数列表

ISHELL_SetPrefs()

说明：

此函数提供了一种方法，以保存包含小程序或类级别首选项的结构。

原型：

int ISHELL_SetPrefs
(
IShell * pIShell,
AEECLSID cls,
uint16 wVer,
void * pCfg,
uint16 nSize
)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 首选项类型的 AEECLSID。
wVer | 首选项版本。
pCfg | 指向要保存的首选项数据的指针。
nSize | 要保存的内存块的大小。

返回值：

如果操作成功，则返回 SUCCESS。

如果参数无效，则返回 EBADPARM。

如果内存不足，则返回 ENOMEMORY。

如果操作失败，

则返回 EFAILED。

备注：

无

另请参阅：

ISHELL_GetPrefs()

返回函数列表

ISHELL_SetTimer()

说明：

此方法允许调用程序设置短期计时器。 到期时，将调用指定的回调函数，并将指定的用户数据指针作为第一参数传递给它。 请注意以下要点：

  • 计时器将在当前时间 + <指定的毫秒数> 时到期
  • 计时器回调发生在应用程序的任务状态下。 系统不会使应用程序开发者管理非任务回调。
  • 所有正常的处理都可以在回调中进行， 其中包括绘制屏幕、写入文件及其它项目。
  • 计时器不会重复。 如果用户希望重复计时器，则必须重置计时器。
  • 指定相同的回调或数据指针将自动覆盖具有相同回调或数据指针的待用计时器。
  • 终止当前激活的小程序时，外壳将扫描计时器列表。 如果小程序终止的结果是被删除（例如，引用计数为 0），并使用指向 IApplet 的数据指针找到了相关计时器，则将删除该计时器。
  • 负超时值被处理为 0 超时值

原型：

int ISHELL_SetTimer
(
IShell * pIShell,
int32 dwMSecs,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIShell | 指向 IShell 接口对象的指针。
dwMSecs | 计时器到期时间（毫秒）。 在当前时间 + dwMSecs时将到期。
pfn | 计时器到期时调用的用户回调。
pUser | 作为唯一参数传递给回调的用户数据指针。

返回值：

如果成功设置计时器，则返回 SUCCESS。

如果参数无效，则返回 EBADPARM。

如果到期时间无效，则返回 EINVALIDTIME。

如果堆中没有足够的内存创建计时器，则返回 ENOMEMORY。

备注：

无

另请参阅：

PFNNOTIFY

ISHELL_GetTimerExpiration()

ISHELL_CancelTimer()

返回函数列表

ISHELL_SetTimerEx()

说明：

此方法允许调用程序设置短期计时器。 到期时，可使用 AEECallback 中指定的用户数据调用 AEECallback 中指定的回调函数。

注意： 计时器将在当前时间 + <指定的毫秒数>时到期，计时器回调将发生在应用程序的任务状态下。 系统不会使应用程序开发者管理非任务回调。

所有的正常处理都可以在回调中进行， 其中包括绘制屏幕、写入文件及其它项目。

计时器不会重复。 如果用户希望重复计时器，则必须重置计时器。

指定相同的回调或数据指针将自动覆盖具有相同回调或数据指针的待用计时器。

终止当前激活的小程序时，外壳将扫描计时器列表。 如果终止小程序的结果是被删除， （例如，引用计数为 0），并使用指向 IApplet 的数据指针找到了相关计时器，
则该计时器将被删除。

负超时值将被处理为 0 超时值

原型：

int ISHELL_SetTimerEx
(
IShell * pIShell,
int32 dwMSecs,
AEECallback * pcb
);

参数：

pIShell | 指向 IShell 对象的指针
dwMSecs | 计时器到期时间（毫秒）。 当前时间 + dwMSecs 时到期
pcb | 用户分配的 AEECallback 结构

返回值：

SUCCESS - 成功设置计时器

EBADCLASS -外壳对象无效

EINVALIDTIME -到期时间无效

ENOMEMORY -堆中无足够的内存创建计时器

备注：

请优先使用此方法而不使用 ISHELL_SetTimer() 和 ISHELL_CancelTimer()。

通过取消以下回调可以取消计时器： CALLBACK_Cancel(pcb)。

另请参阅：

ISHELL_SetTimer()

ISHELL_CancelTimer()

返回函数列表

ISHELL_ShowCopyright()

说明：

此函数可使应用程序显示小程序的版权信息。 小程序可以使用此函数在屏幕上显示版权和其它相关信息。 这些信息可以从该小程序的模块信息文件 (MIF) 中获取。 可显示的信息如下：

  • 应用程序名称
  • 应用程序图标
  • 版权字符串
  • 公司名称

注意： 字符串的长度必须小于 24 个字符。 这些信息以对话框的形式显示并保留在屏幕上，直到设备用户按下清除按钮清除对话框。

原型：

boolean ISHELL_ShowCopyright(IShell * pIShell)

参数：

pIShell
指向 IShell 接口对象的指针。

返回值：

如果成功显示版权信息，则返回 TRUE。

如果显示版权信息失败，则返回 FALSE。

备注：

此函数内部的实现使用 ISHELL_Prompt()。

另请参阅：

无

返回函数列表

ISHELL_StartApplet()

说明：

此函数用于指示 AEE 外壳启动指定 32 位 ClassID 所关联的小程序。 如果可以支持并启动请求的类，AEE 外壳将加载并启动小程序。 启动小程序之前，该调用会立即返回到调用程序。

由于小程序是异步启动的，因此如果未找到指定的小程序 classID，函数将返回 TRUE 但不启动小程序。 如果启动或恢复了小程序，则将清除显示并向 IAPPLET_HandleEvent() 发送 EVT_APP_START 或 EVT_APP_RESUME 事件及 AEEAppStart 参数块。 如果小程序由其它小程序启动，则将中止当前激活的小程序。

原型：

int ISHELL_StartApplet(IShell * pIShell, AEECLSID cls)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 32 位小程序 ClassID。

返回值：

如果已创建并启动小程序，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持指定的类，则返回 ECLASSNOTSUPPORT。

如果小程序已到期，则返回 EEXPIRED。

备注：

无

另请参阅：

ISHELL_CreateInstance()

ISHELL_CanStartApplet()

ISHELL_CloseApplet()

ISHELL_ActiveApplet()

返回函数列表

ISHELL_StartAppletArgs()

说明：

此方法允许在启动 BREW 应用程序向它传递命令行参数。 它向 AEE 传递参数，指示 AEE 启动指定的 32 位类 ID 所关联的小程序。 如果可以支持并启动所请求的类，AEE 将加载并启动小程序。 请注意，启动小程序之前，该调用会立即返回到调用程序，
小程序将异步启动。 因此，如果找不到指定的小程序类 ID，函数将返回 TRUE 但不启动小程序。

如果启动或恢复了小程序，则将清除显示并向 ISHELL_HandleEvent() 发送 EVT_APP_START 或 EVT_APP_RESUME 以及 AEEAppStart 参数块。

注意：

  • ISHELL_StartApplet() 为异步函数。 直到将控制释放给系统以后，新的小程序才会启动。
  • ISHELL_StartApplet() 使得当前小程序在新的应用程序启动之前，立即接收 EVT_APP_SUSPEND 事件。
  • 启动参数将作为 AEEAppStart 块中的字符串传递。 如果参数不为 NULL，应用程序还可接收 EVT_APP_BROWSE_FILE 或 EVT_APP_BROWSE_URL。

如果应用程序作为恢复过程的一部分重新启动，它将不处理 EVT_APP_SUSPEND 命令，不接收后续 EVT_APP_START 通知的参数块。

原型：

int ISHELL_StartAppletArgs
(
IShell *pIShell,
AEECLSID cls,
const char * pszArgs
)

参数：

pIShell | 指向 IShell 对象的指针
cls | 32 位小程序的类 ID
pszArgs | 应用程序参数的 ASCIIZ 字符串。

返回值：

如果已创建和启动小程序，则返回 SUCCESS

如果其它小程序已启动，则返回 EALREADY

如果提供的外壳类无效，则返回 EBADCLASS

如果内存不足，则返回 ENOMEMORY

如果不支持指定的类，则返回 ECLASSNOTSUPPORT

如果小程序已到期，则返回 EEXPIRED

备注：

无

另请参阅：

ISHELL_CreateInstance

ISHELL_StartAppletEx

ISHELL_BrowseFile

ISHELL_BrowseURL

返回函数列表

ISHELL_StartAppletEx()

说明：

此函数用于指示 AEE 使用指定的标记，来启动指定的 32 位 ClassID 所关联的小程序。 此调用与 ISHELL_StartApplet() 函数类似，但有以下几点不同：

  • 如果指定了 SSA_NO_VOICE_CALL 标记，则小程序不会在语音呼叫时启动。
  • 如果指定了 SSA_AFTER_VOICE_CALL 标记，则将在结束当前语音呼叫，并清除呼叫结束时显示的所有对话框（由 OEM 定义）后，启动小程序。
  • 如果调用 SSA_CONFIG 标记，小程序将使用 EVT_APP_CONFIG 事件启动。
  • 如果调用 SSA_HIDDEN_CONFIG 标记，小程序将使用 EVT_APP_HIDDEN_ CONFIG 事件启动。

注意：如果没用指定 SSA_CONFIG 或 SSA_HIDDEN_CONFIG 标记，应用程序将使用标准 EVT_APP_START 事件启动。

原型：

int ISHELL_StartAppletEx(IShell * pIShell, AEECLSID cls,uint16 wFlags)

参数：

pIShell | 指向 IShell 接口对象的指针。
cls | 32 位小程序 ClassID。
wFlags | 行为标记 (SSA_XXXX)。

返回值：

如果已创建并启动小程序，则返回 SUCCESS。

如果其它小程序已启动，则返回 EALREADY

如果提供的外壳类无效，则返回 EBADCLASS。

如果内存不足，则返回 ENOMEMORY。

如果不支持指定的类，则返回 ECLASSNOTSUPPORT。

如果小程序已到期，则返回 EEXPIRED。

备注：

无

另请参阅：

ISHELL_StartApplet()

ISHELL_BrowseFile()

ISHELL_BrowseURL()

返回函数列表


ISocket 接口

ISocket 接口可提供连接、传输与接收，以及关闭通过 INETMGR_OpenSocket() 打开的 TCP 和 UDP 套接字的方法。

注意：应用程序必须拥有“网络”或“全部”优先级，才能调用该接口的函数。

打开套接字后会立即调用 ISOCKET_Connect() 函数。 如果设备的网络子系统（物理层、
RLP 和 PPP）不处于激活状态，此函数将首先建立必要的低层协议连接。 对于 TCP 套接字，ISOCKET_Connect() 将建立与指定 IP 地址和端口号的 TCP 连接。 对于 UDP 套接字，调用 ISOCKET_Connect() 时提供的 IP 地址和端口号将用作套接字写操作的默认设置。 因此，对于 UDP 套接字，调用程序可以指定每次读写操作的目标 IP 地址和端口号，以使数据发往或接自多个 IP 地址和端口。

连接套接字后，即可通过套接字，使用读写操作来交换数据。 所有数据传输操作都是非阻塞和异步的，回调函数用于向调用程序通知执行读写操作的套接字的可用性。 调用程序可以使用 ISOCKET_Readable() 提供回调函数的地址，在有数据可读取时必须调用此回调函数。
同样，ISOCKET_Writeable() 可以注册在套接字可供写入时调用的回调函数。 只要 BREW 发现任何需要应用程序使用该接口来纠正的套接字错误，都将调用回调函数。 函数 ISOCKET_Cancel() 用于取消待用的回调操作，从而防止应用程序在其等待的套接字状态发生变化时接收通知。

函数 ISOCKET_Read() 和 ISOCKET_Write() 用于从 TCP 套接字读取数据或向其中写入数据。 如果读写无法进行，则 ISOCKET_Read() 和 ISOCKET_Write() 将返回发生阻塞的指示。 这时，调用程序可以使用 ISOCKET_Readable() 或 ISOCKET_Writeable() 安排在阻塞消失后获得通知。 如果实际读写少于请求的字节数，请重复调用 ISOCKET_Read() 或 ISOCKET_Write() 以完成数据传输。

如果应用程序使用多个间断的缓冲区进行读写操作，可使用 ISOCKET_ReadV() 和 ISOCKET_WriteV() 函数来收发 TCP 套接字上的数据。 ISOCKET_ReadV() 和 ISOCKET_WriteV() 与使用单个缓冲区指针作为参数的 ISOCKET_Read() 和 ISOCKET_Write() 不同，它们都以缓冲区描述符数组作为输入，每个数组元素可以指定一个缓冲区的长度（字节）和起始地址。 这些函数试图从数组中第一个缓冲区开始，传输与缓冲区长度总数相等的数据量。

函数 ISOCKET_RecvFrom() 和 ISOCKET_SendTo() 用于通过 UDP 套接字交换数据。 这两个函数都允许数据发往和接收自多个 IP 地址和端口号。 与 TCP 套接字一样，如果读或写操作没有立即进行，应用程序可以调用 ISOCKET_Readable() 或 ISOCKET_Writeable() 指定回调
函数。

函数 ISOCKET_Bind() 可以使本地端口号与套接字相关联（如果应用程序没有在 ISOCKET_Connect() 之前调用此函数，本地端口号将使用默认值）。 函数 ISOCKET_GetLastError() 用于返回 ISocket 接口 函数检测到的上一个错误的错误代码。 如果这类函数返回非成功的结果，ISOCKET_GetLastError() 将提供详细信息说明函数未能成功执行的原因。 函数 ISOCKET_GetPeerName() 用于返回最近在套接字上交换数据的实体的 IP 地址和端口号。

数据传输结束后，调用 ISOCKET_Release() 关闭套接字连接并释放 ISocket 接口及相关
资源。

使用套接字服务

  1. 调用 ISHELL_CreateInstance() 创建 INetMgr 接口 实例。
  2. 调用 INETMGR_OpenSocket() 创建 ISocket 接口的实例（以打开 TCP 或 UDP 套接字）。
  3. 调用 ISOCKET_Connect() 建立与网络实体（应用程序将与其通信）的套接字
    连接。
  4. 使用 ISocket 接口的函数操作套接字。

在套接字上读写数据

  1. 调用上述相关的（TCP/UDP、单/多 I/O 缓冲区）读写函数。
  2. 如果函数返回阻塞指示，则调用 ISOCKET_Readable() 或 ISOCKET_Writeable() 稍后重试该操作。
  3. 如果传输了少于请求的字节数，则再次调用读写函数实现剩余的数据传输。
  4. 重复步骤 1-3，直到全部数据传输完毕。
  5. 调用 ISOCKET_Bind() 指定套接字的本地端口号。
  6. 调用 ISOCKET_GetPeerName() 获取套接字最近的通信伙伴的 IP 地址和端口号。
  7. 完成数据传输后，调用 ISOCKET_Release() 关闭套接字。
  8. 调用 INETMGR_Release() 释放 INetMgr 接口实例。

要包含的头文件列表

需要以下头文件：

AEENet.h

函数列表

此接口的函数包括：

ISOCKET_AddRef()

ISOCKET_Bind()

ISOCKET_Cancel()

ISOCKET_Connect()

ISOCKET_GetLastError()

ISOCKET_GetPeerName()

ISOCKET_IOCtl()

ISOCKET_Read()

ISOCKET_Readable()

ISOCKET_ReadV()

ISOCKET_RecvFrom()

ISOCKET_Release()

ISOCKET_SendTo()

ISOCKET_Write()

ISOCKET_Writeable()

ISOCKET_WriteV()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISOCKET_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOCKET_Release()

返回函数列表

ISOCKET_Bind()

说明：

此函数用于将套接字与本地地址和端口相关联。 绑定函数用于未连接的套接字;

通常绑定无连接的（数据报）套接字， 而不支持绑定面向连接的（流）套接字。

在调用套接字函数创建套接字后，它将位于名称空间（地址族）中，但是并没有分配名字。 向该地址传递 AEE_INADDR_ANY（零）明确要求将该套接字分配给任意本地地址。

请注意，目前尚不支持绑定到指定本地 IP 地址的功能，AEE_INADDR_ANY 是 INAddr 参数的唯一有效值。 本地 IP 地址将由套接字库自动分配。

另外请注意 AEE_NET_WOULDBLOCK 结果的可能性。 这种情况通常只在必须建立网络连接（例如，PPP 连接）时发生。 这时，Bind() 将返回 AEE_NET_WOULDBLOCK，并可再次调用以获取最终结果（错误或成功）。 调用 ISOCKET_Writeable() 可以获取再次调用 Bind() 的时间通知。 （请注意，和 Write() 一样，ISOCKET_Writeable() 回调无法确保完成后续的 Bind() 调用，因此调用程序必须准备再次接收 AEE_NET_WOULDBLOCK。）

在返回非 WOULDBLOCK 结果前，不要求用户调用 Bind()。 用户可以继续尝试使用 ISOCKET_SendTo() 或 ISOCKET_RecvFrom() 发送或接收数据，这时绑定操作
（和网络启动）将在后台进行，启动阶段的所有错误将反映在 ISOCKET_SendTo() 或 ISOCKET_RecvFrom() 的错误结果中。

原型：

int ISOCKET_Bind(ISocket * pISocket, INAddr a, uint16 wPort)

参数：

pISocket | 指向要连接的 ISocket 接口对象的指针。
a | IP 地址。
wPort | 端口。

返回值：

如果成功，则返回 AEE_NET_SUCCESS。

如果出错，则返回 AEE_NET_ERROR。

如果操作阻塞，则返回 AEE_NET_WOULDBLOCK。在发生回调时，应调用 ISOCKET_Writeable() 和 ISOCKET_Bind()。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。 可能返回的错误代码如下：

AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_EOPNOTSUPP | 请求了指定的本地 IP 地址（不支持），或该套接字为 TCP 套接字
AEE_NET_EADDRINUSE | 本地地址已在使用。
AEE_NET_EINVAL | 套接字已具有本地名称。
AEE_NET_EFAULT | 指定的地址参数无效。
AEE_NET_EAFNOSUPPORT | 不支持地址族。
AEE_NET_GENERAL_FAILURE | 常规失败。
AEE_NET_WOULDBLOCK | 目前没有可用的数据，请稍后再试（请参阅 ISOCKET_Readable()）。

当前不支持指定地址。

另请参阅：

返回函数列表

ISOCKET_Cancel()

说明：

此函数允许应用程序取消（注销）先前使用 ISOCKET_Readable() 或 ISOCKET_Writeable() 注册的回调函数。 取消操作将废止前面的 ISOCKET_Readable() 或 ISOCKET_Writeable() 的作用，这样套接字在操作中将不再调用该回调函数。 如果 pfn 和 pUser 均为 NULL 时，则将取消所有已注册的回调。

原型：

void ISOCKET_Cancel(ISocket * pISocket, PFNNOTIFY pfn, void * pUser)

参数：

pISocket | 指向需要注销其回调函数的 ISocket 接口的指针。
pfn | 指向需要注销的回调函数的指针。
pUser | 用于注册回调的回调数据。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

返回函数列表

ISOCKET_Connect()

说明：

对于 AEE_SOCK_STREAM 类型的套接字，此函数将尝试初始化与指定地址和端口的 TCP 连接。 对于 AEE_SOCK_DGRAM 类型的套接字，指定的主机和端口与套接字关联，并作为后续 ISOCKET_Write() 调用的默认目的地址。

在执行上述套接字特定行为之前，ISOCKET_Connect() 将尝试获取 IP 地址并确保基础网络层已作好通信准备。 这可能涉及使用 DCMA 设备或 QNC 的 CDMA 数据包数据所组成的网络子系统，建立因特网连接（如果尚未建立此连接）。

在建立因特网连接（对于 AEE_SOCK_STREAM 套接字，即 TCP 连接）成功或失败后，将调用指定的回调。 回调将收到说明连接操作如何完成的错误代码。

原型：

int ISOCKET_Connect
(
ISocket * pISocket,
INAddr a,
INPort wPort,
PFNCONNECTCB pfn,
void * pUser
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
a | IP 地址。
wPort | 端口。
pfn | 连接操作成功或失败时，AEE 调用的回调函数的地址。
pUser | 调用回调函数时传递给它的用户自定义数据。

返回值：

如果成功，则返回 AEE_NET_SUCCESS。 这表示在调用程序释放控制后将调用
回调。

如果传递的回调指针 (pfn) 为 NULL，则返回 AEE_NET_ERROR。

只有在这种情况下，将不调用回调。

备注：

假定 INAddr 和 INPort 参数是以网络字节顺序（例如，高位优先）排列。 这一点可以影响模拟环境及潜在设备目标相互之间的移植性。 下列值之一将传递给回调，这些值用于描述连接操作的完成情况：

AEE_NET_SUCCESS | 成功完成连接，并且套接字已准备好进行读或写操作。
AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_ECONNREFUSED | 拒绝连接尝试。
AEE_NET_ETIMEDOUT | 连接尝试超时。
AEE_NET_EFAULT | 地址参数无效。
AEE_NET_EIPADDRCHANGED | IP 地址因 PPP 再同步而改变。
AEE_NET_EISCONN | 已连接套接字（结果已由前面的 Connect() 调用接收）。
AEE_NET_ENETDOWN | 网络子系统不可用。
AEE_NET_EOPNOTSUPP | 指定的服务器地址无效。
AEE_NET_EADDRREQ | 要求目的地址。
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

PFNCONNECTCB

INAddr

INPort

返回函数列表

ISOCKET_GetLastError()

说明：

此函数用于返回给定套接字发生的上一个错误。 返回值取决于最近调用的函数。
每个函数的资料均说明了在其后调用此函数将返回的结果。

原型：

int ISOCKET_GetLastError(ISocket * pISocket)

参数：

pISocket
指向 ISocket 接口对象的指针。

返回值：

最近发生的错误。

备注：

无

另请参阅：

无

返回函数列表

ISOCKET_GetPeerName()

说明：

此函数用于返回对等端的 IP 地址和端口（例如，最近与该套接字通信的实体的
IP地址）。

原型：

int ISOCKET_GetPeerName
(
ISocket * pISocket,
INAddr * pa,
uint16 * pwPort
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pa | 指向 IP 地址的指针。
pwPort | 指向端口的指针。

返回值：

如果成功，则返回 AEE_NET_SUCCESS。

否则，将返回说明网络故障的网络错误代码。

备注：

无

另请参阅：

INAddr

返回函数列表

ISOCKET_IOCtl()

说明：

此函数用于控制 ISocket 的一些行为，例如连接超时。 它的形式与 SYSV 的 ioctl 相似，其中的编码参数将由此处所列举的 _IOCTL_ 宏来指定。 它用于超出对象签名的特殊行为， 因此具有通用性。

原型：

int ISOCKET_IOCtl(ISocket * pISocket, int nOption, uint32 dwVal);

参数：

pISocket | 指向 ISocket 接口的指针
nOption | 选项 id
dwVal | 选项值

返回值：

如果选项 id 已知且指定的操作成功，则返回 SUCCESS

如果未识别选项 id，则返回 EUNSUPPORTED

根据所指定的选项 id，可能返回其它错误代码

备注：

以下为当前支持的选项 id：

ISOCKET_IOCTL_GCLOSER | dwVal 设置为指向 ISocketCloser 结构的指针，ISocket 的当前套接字关闭回调将填写该指针。
ISOCKET_IOCTL_SCLOSER | dwVal 设置为指向 ISocketCloser 结构的指针， 它将指定 ISocket 新的关闭回调
ISOCKET_IOCTL_CONNTIMEOUT | dwVal 设置为等待成功连接的时间（毫秒）
ISOCKET_IOCTL_PRIORITY | dwVal 设置为 TRUE，以区分连接或套接字吞吐数据的优先次序。
ISOCKET_IOCTL_QI | dwVal 设置为指向 ISocketQI 的指针，以调用 QueryInterface()。

另请参阅：

无

返回函数列表

ISOCKET_Read()

说明：

此函数用于将套接字中的数据读入单个缓冲区（指定为该函数的一个参数）。 该函数始终立即返回。 如果没有可用的数据而连接仍然有效，ISOCKET_Read() 将返回 AEE_NET_WOULDBLOCK。 要得到再次调用 ISOCKET_Read() 的时间通知，调用程序必须调用 ISOCKET_Readable()。

原型：

int32 ISOCKET_Read(ISocket * pISocket, byte * pbDest, uint16 wSize)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pbDest | 保存要接收的数据的缓冲区指针。
wSize | 指定要读取的字节数。

返回值：

bytes_read，任意正数，指示已成功读入所提供缓冲区的字节数。

如果不再有要接收的数据，且对等端已断开连接，则返回 0（零）。

如果目前没有可用的数据，需稍后再试（请参阅 ISOCKET_Readable()），则返回 AEE_NET_WOULDBLOCK。

如果套接字未处于接收数据的有效状态，则返回 AEE_NET_ERROR。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。 可能返回的错误代码有：

AEE_NET_EBADF | 指定的套接字描述符无效
AEE_NET_ENOTCONN | 未连接套接字
AEE_NET_ECONNRESET | 服务器已重置 TCP 连接
AEE_NET_ECONNABORTED | TCP 连接由于超时或其它故障而中断
AEE_NET_EIPADDRCHANGED | IP 地址更改，导致 TCP 连接重置
AEE_NET_EPIPE | 管道损坏
AEE_NET_EADDRREQ | 要求目的地址
AEE_NET_ENETDOWN | 网络子系统不可用
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

无

返回函数列表

ISOCKET_Readable()

说明：

此函数使应用程序可以在指定套接字进行无阻塞读取操作（Read、ReadV 或 RecvFrom）时，注册由 AEE 调用的回调函数。 这一过程可以包括返回数据、返回错误代码或返回 0（零）表示关闭的连接 - AEE_NET_WOULDBLOCK 除外。 此函数通常在前一个读取尝试返回 AEE_NET_WOULDBLOCK 后使用，但是即使未调用读取函数也可以使用它。

注意：无法确保回调之后读取函数会有所进展， 因此调用程序必须准备在读取函数返回 AEE_NET_WOULDBLOCK 后再次调用 ISOCKET_Readable()。

原型：

void ISOCKET_Readable(ISocket * pISocket, PFNNOTIFY pfn, void * pUser)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pfn | 回调函数的地址。 AEE 在套接字准备好读取或关闭时将调用此函数。 如果该值为 NULL，将取消前面调用 ISOCKET_Readable（如果有）注册的 Readable 回调函数。 如果传递的 pfn 为 NULL，则始终返回 AEE_NET_SUCCESS。
pUser | 调用回调函数时传递给它的用户自定义数据。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

返回函数列表

ISOCKET_ReadV()

说明：

此函数用于将套接字中的数据读入由 iov[] 数组条目说明的一个或多个缓冲区。 该函数始终立即返回。 如果没有可用数据而连接仍然有效，ISOCKET_ReadV() 将返回 AEE_NET_WOULDBLOCK。 要得到再次调用 ISOCKET_ReadV() 的时间通知，调用程序必须调用 ISOCKET_Readable()。

原型：

int32 ISOCKET_ReadV
(
ISocket * pISocket,
SockIOBlock iov[],
uint16 iovcount
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
iov | 将读入数据的 SockIOBlock 结构数组。
iovcount | 指定 iov 数组中的元素数目。

返回值：

bytes_read，任意正数，指示已成功读入所提供缓冲区的字节数。

如果不再有要接收的数据，且对等端已断开连接，则返回 0（零）。

如果目前没有可用的数据，需稍后再试（请参阅 ISOCKET_Readable()），则返回 AEE_NET_WOULDBLOCK。

如果套接字未处于接收数据的有效状态，则返回 AEE_NET_ERROR。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。 可能返回的错误代码包括：

AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_ENOTCONN | 未连接套接字。
AEE_NET_ECONNRESET | 服务器已重置 TCP 连接。
AEE_NET_ECONNABORTED | TCP 连接由于超时或其它故障而中断。
AEE_NET_EIPADDRCHANGED | IP 地址更改，导致 TCP 连接重置。
AEE_NET_EPIPE | 管道损坏。
AEE_NET_EADDRREQ | 要求目的地址。
AEE_NET_ENETDOWN | 网络子系统不可用。
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分。
AEE_NET_EWOULDBLOCK | 操作将中断。
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

SockIOBlock

返回函数列表

ISOCKET_RecvFrom()

说明：

此函数用于读取 UDP 套接字中的数据并记录发送方的 IP 地址和端口。 此函数始终立即返回读取的字节数。 如果没有数据包到达而套接字仍处于有效状态，ISOCKET_RecvFrom() 将返回 AEE_NET_WOULDBLOCK。ISOCKET_Readable() 可用于接收再次尝试 ISOCKET_RecvFrom() 的通知。

原型：

int32 ISOCKET_RecvFrom
(
ISocket * pISocket,
byte * pBuff,
uint16 wbytes,
uint16 wflags,
INAddr * pa,
INPort * pwPort
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pBuff | 保留接收数据的缓冲区。
wBytes | 缓冲区的大小（字节数）。
wflags | 未使用，必须设置为零。
pa | 指向 IP 地址的指针。
pwPort | 指向端口的指针。

返回值：

bytes_read，任意正数，指示已成功读入所提供缓冲区的字节数。

如果不再有要接收的数据，且对等端已断开连接，则返回 0（零）。

如果目前没有可用的数据，需稍后再试（请参阅 ISOCKET_Readable()），则返回 AEE_NET_WOULDBLOCK。

如果套接字未处于接收数据的有效状态，则返回 AEE_NET_ERROR。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码，可能返回的下列错误代码如下：

AEE_NET_EEOF | 文件结束。
AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_EAFNOSUPPORT | 不支持地址族。
AEE_NET_EADDRREQ | 要求目的地址。
AEE_NET_ENETDOWN | 网络子系统不可用。
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分。
AEE_NET_EOPNOTSUPP | 不支持选项。
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

INAddr

INPort

返回函数列表

ISOCKET_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOCKET_AddRef()

返回函数列表

ISOCKET_SendTo()

说明：

此函数用于将 UDP 数据包从绑定到套接字的本地端口发送到指定的 IP 地址和端口。 此函数必须用于 AEE_NET_DGRAM (UDP) 类型的套接字，而非 AEE_NET_STREAM (TCP) 类型的套接字。 如果套接字尚未绑定到本地地址和端口，此函数可将其绑定到一个端口。

套接字总是在无阻塞模式下运行。 此函数会立即返回；如果成功，将返回写入的字节数。 如果未能发送字节而连接仍然有效，此函数将返回 AEE_NET_WOULDBLOCK。 要得到再次调用 ISOCKET_SendTo() 的时间通知，调用程序必须调用 ISOCKET_Writeable()。

原型：

int32 ISOCKET_SendTo
(
ISocket * pISocket,
byte * pBuff,
uint16 wBytes,
uint16 wflags,
INAddr a,
INPort wPort
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pBuff | 包含要发送的数据的缓冲区。
wBytes | 缓冲区的大小（字节数）。
wflags | 未使用，必须设置为零。
a | IP 地址。
wPort | 端口。

返回值：

AEE_NET_WOULDBLOCK | 此次无法发送数据。 请使用 ISOCKET_Writeable() 等待就绪。 在传输缓冲区已经填充或正在建立网络连接时会遇到这种 情况。
AEE_NET_ERROR | 指示失败。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。可能返回的错误代码如下：

AEE_NET_EEOF | 文件结束
AEE_NET_EBADF | 指定的套接字描述符无效
AEE_NET_EAFNOSUPPORT | 不支持地址族
AEE_NET_EADDRREQ | 要求目的地址
AEE_NET_ENETDOWN | 网络子系统不可用
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分
AEE_NET_EOPNOTSUPP | 不支持选项
AEE_NET_GENERAL_FAILURE | 常规失败

另请参阅：

INAddr

INPort

返回函数列表

ISOCKET_Write()

说明：

此函数用于从单个缓冲区向连接的套接字写入数据。 此函数始终立即返回成功写入的字节数。 如果未能写入字节而连接仍然有效，ISOCKET_Write() 将返回 AEE_NET_WOULDBLOCK。 要得到再次调用的时间通知，调用程序必须调用 ISOCKET_Writeable()。

原型：

int32 ISOCKET_Write(ISocket * pISocket, byte * pBuffer, uint16 wBytes)

参数：

pISocket | 指向 ISocket 接口对象的指针。
pBuffer | 指向发送数据的缓冲区指针。
wBytes | 指定缓冲区的大小（字节数）。

返回值：

bytes_written ( > 0)，任意正数，指示已成功写入的字节数。

如果此次未能写入字节，需稍后再试（请参阅 ISOCKET_Writeable()），则返回 AEE_NET_WOULDBLOCK。

如果写入字节失败，则返回 AEE_NET_ERROR。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。 可能返回的错误代码如下。

AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_ENOTCONN | 未连接套接字。
AEE_NET_ECONNRESET | 服务器已重置 TCP 连接。
AEE_NET_ECONNABORTED | TCP 连接由于超时或其它故障而中断。
AEE_NET_EIPADDRCHANGED | IP 地址更改，导致 TCP 连接重置。
AEE_NET_EPIPE | 管道损坏。
AEE_NET_EADDRREQ | 要求目的地址。
AEE_NET_ENETDOWN | 网络子系统不可用。
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分。
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

无

返回函数列表

ISOCKET_Writeable()

说明：

此函数使应用程序可以在指定套接字进行无阻塞写操作（ISOCKET_Write()、ISOCKET_WriteV() 或 ISOCKET_SendTo()）时，注册由 AEE 调用的回调函数。
这一过程包括写入数据或返回错误代码 -- AEE_NET_WOULDBLOCK 除外。 此函数通常在前一个写尝试返回 AEE_NET_WOULDBLOCK 后使用，但即使未调用写函数也可以使用它。

注意：无法确保回调之后写入函数会有所进展，因此调用程序必须随时准备在写函数返回 AEE_NET_WOULDBLOCK 后再次调用 ISOCKET_Writeable()。

原型：

void ISOCKET_Writeable(ISocket * pISocket, PFNNOTIFY pfn, void * pUser)

参数：

pISocket | 指向要注册回调函数的 ISocket 接口对象的指针。
pfn | 回调函数的地址。 AEE 在套接字准备接收数据或关闭时将调用此函数。 如果该值为 NULL，将取消前面调用 ISOCKET_Writeable() 注册的 Writeable 回调函数。
pUser | 调用回调函数时传递给它的用户自定义数据。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

返回函数列表

ISOCKET_WriteV()

说明：

此函数用于向连接的套接字写入数据。 它可以将 iov[] 数组元素说明的一个或多个缓冲区的数据集中到一次写操作。 对于 AEE_SOCK_STREAM (TCP) 套接字，独立调用 ISOCKET_Write() 的行为会有所不同，因为多次调用 ISOCKET_Write() 会产生一些不必要的 TCP 数据包。 对于 AEE_SOCK_DGRAM (UDP) 套接字，独立缓冲区可作为单独数据包来处理。

此函数始终立即返回成功写入的字节数。 如果未能写入字节而连接仍然有效，ISOCKET_Write() 将返回 AEE_NET_WOULDBLOCK。 要得到再次调用 ISOCKET_WriteV() 的时间通知，调用程序必须调用 ISOCKET_Writeable()。

原型：

int32 ISOCKET_WriteV
(
ISocket * pISocket,
SockIOBlock iov[],
uint16 wiovcount
)

参数：

pISocket | 指向 ISocket 接口对象的指针。
iov[ ] | 包含要发送的单独缓冲区的 SockIOBlock 数组
wiovcount | SockIOBlock 结构中的条目数。

返回值：

bytes_written ( > 0)，任意正数，指示从所有 iov[] 缓冲区中成功写入的总字节数。

如果此次未能写入字节，需稍后再试（请参阅 ISOCKET_Writeable()），则返回 AEE_NET_WOULDBLOCK。

如果写入字节失败，则返回 AEE_NET_ERROR。

备注：

调用 ISOCKET_GetLastError() 可以获取指定的错误代码。 可能返回的错误代码如下

AEE_NET_EBADF | 指定的套接字描述符无效。
AEE_NET_ENOTCONN | 未连接套接字。
AEE_NET_ECONNRESET | 服务器已重置 TCP 连接。
AEE_NET_ECONNABORTED | TCP 连接由于超时或其它故障而中断。
AEE_NET_EIPADDRCHANGED | IP 地址更改，导致 TCP 连接重置。
AEE_NET_EPIPE | 管道损坏。
AEE_NET_EADDRREQ | 要求目的地址。
AEE_NET_ENETDOWN | 网络子系统不可用。
AEE_NET_EFAULT | 应用程序缓冲区不是地址空间的有效部分。
AEE_NET_GENERAL_FAILURE | 常规失败。

另请参阅：

SockIOBlock

返回函数列表


ISound 接口

ISound 接口用于提供基本的声音服务。 这些服务可使开发者使用蜂鸣、铃声、振动、各种音调以及音调列表。 ISound 定义了一组音调，能够播放一段时间或连续播放直到停放。 音调标识符可以放入列表，使用单个函数调用即可播放列表中的所有音调。 ISound 接口还提供了可以获取和设置音量的函数。

使用 ISound 接口

  1. 创建 ClassID 为 AEECLSID_SOUND 的 ISound 接口实例。
  2. 使用 ISOUND_RegisterNotify() 注册状态回调函数。 ISound 始终通过该回调函数与小程序通信。 回调函数传送关于用户数据、状态回调类型（AEE_SOUND_STATUS_CB、AEE_SOUND_VOLUME_CB）和状态（AEE_SOUND_SUCCESS、AEE_SOUND_PLAY_DONE、AEE_SOUND_FAILURE）的信息。 数据（如果有）将通过指向 AEESoundPlayerCmdData 的 dwParam 参数在回调中返回。 否则 dwParam 为 NULL。 您无需注册回调函数，并可选择不获取任何 ISound 事件，如以下示例所示：
         ISOUND_RegisterNotify(pISound, NULL, NULL);
  3. 使用 ISOUND_Set() 设置 ISound 参数。 这一步是可选的，如果不执行，ISound 将使用该参数的默认值。 完成这些步骤后，即可使用 ISound。 关于每个函数的详细信息，请参阅 ISound 函数说明。

音调数据库

在目标设备上，设备制造商可以将 AEESoundTone 类型的元素映射到音调数据库中的
对应 ID。

在 BREW Emulator 中，设备制造商或小程序开发者可以定义自己的 WAV 格式音调文件，
并将其添加到 BREW Emulator 音调数据库中。 这些音调根据 AEESoundTone 类型，保存在 <\BREW> 目录（安装 BREW AEE 的目录）的 <\bin\DataFiles> 子目录下。 例如，要将 AEE_TONE_0 添加到 BREW Emulator，请在 <\BREW> 目录（安装 BREW AEE的目录）
的 <\bin\DataFiles> 子目录下将 WAV 文件另存为“AEE_TONE_0.wav”。 该机制同样适用于 ISHELL_Beep() 函数所需要的 BeepType。 例如，要创建自己的 BEEP_ALERT 音调，请在 <\BREW> 目录（安装 BREW AEE 的目录）的 <\bin\DataFiles> 子目录下将您的 WAV 文件另存为“BEEP_ALERT.wav”。 我们提供了几种示例音调和所有的蜂鸣类型， 其用法将在示例声音小程序中详细说明。

要包含的头文件列表

需要以下头文件：

AEESound.h

函数列表

该接口的函数包括：

ISOUND_AddRef()

ISOUND_Get()

ISOUND_GetVolume()

ISOUND_PlayFreqTone()

ISOUND_PlayTone()

ISOUND_PlayToneList()

ISOUND_RegisterNotify()

ISOUND_Release()

ISOUND_Set()

ISOUND_SetDevice()

ISOUND_SetVolume()

ISOUND_StopTone()

ISOUND_StopVibrate()

ISOUND_Vibrate()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISOUND_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOUND_Release()

返回函数列表

ISOUND_Get()

说明：

此函数用于获取 ISound 接口对象的设备属性。

原型：

void ISOUND_Get(ISound * pISound, const AEESoundInfo * pSoundInfo)

参数：

pISound | [in] | 指向 ISound 接口对象的指针。
pSoundInfo | [out] | 包含 ISound 设备属性的结构。

返回值：

无

备注：

无

另请参阅：

AEESoundInfo

ISOUND_Set()

返回函数列表

ISOUND_GetVolume()

说明：

此函数用于获取当前设备/方法对所使用的音量。

原型：

void ISOUND_GetVolume(ISound * pISound)

参数：

pISound
指向 ISound 接口对象的指针。

返回值：

无

备注：

无

副作用：

音量通过 <\BREW> 目录（安装 BREW 的目录）下 <\bin\DataFiles> 子目录中回调函数的 AEESoundCmdData 结构指针返回到客户端。 结果包括状态以及当前音量。
可能的状态值如下：

AEE_SOUND_SUCCESS，成功获取当前音量。 回调函数的 dwParam 参数是指向 AEESoundCmdData 结构的指针，其中包含该音量。

AEE_SOUND_FAILURE，获取当前音量失败并将音量重置为 0。

当前音量作为附加数据包括在状态事件中。

另请参阅：

无

返回函数列表

ISOUND_PlayFreqTone()

说明：

此函数用于在指定的时间内播放给定高低频率的音调。

注意：当前版本 BREW 的 BREW Emulator 不支持此函数。

原型：

void ISOUND_PlayFreqTone
(
ISound * pISound,
uint16 wHiFreq,
uint16 wLoFreq,
uint16 wDuration
)

参数：

pISound | 指向 ISound 接口对象的指针。
wHiFreq | DTMF 对的高频率。
wLoFreq | DTMF 对的低频率。
wDuration | 音调播放时间（毫秒）。

返回值：

无

备注：

如果播放时间设置为 0（零），则音调将播放到调用 ISOUND_StopTone() 为止。 BREW 设备支持此函数，但 BREW Emulator 不支持。

副作用：

操作结果将通过回调函数指针发送给客户端。 而且在操作完成后，将通过同一回调函数指针通知客户端。

可能的状态值如下：

AEE_SOUND_SUCCESS，成功播放音调。

AEE_SOUND_FAILURE，播放音调失败。

AEE_SOUND_PLAY_DONE，音调播放完毕或被其它音调代替。

另请参阅：

无

返回函数列表

ISOUND_PlayTone()

说明：

此函数用于在指定的时间内播放给定音调 ID 的音调。

原型：

void ISOUND_PlayTone(ISound * pISound, AEESoundToneData toneData)

参数：

pISound | 指向 ISound 接口对象的指针。
toneData | 包含要播放的音调 ID 和播放时间（毫秒）的结构。

返回值：

无

备注：

如果列表中某个音调的播放时间设置为 0（零），则该音调将播放到调用 ISOUND_StopTone() 为止。

副作用：

操作结果将通过回调函数指针发送给客户端。 而且在操作完成后，将通过同一回调函数指针通知客户端。

可能的状态值如下：

AEE_SOUND_SUCCESS，成功播放音调。

AEE_SOUND_FAILURE，播放音调失败。

AEE_SOUND_PLAY_DONE，音调播放完毕或被其它音调代替。

另请参阅：

AEESoundToneData

返回函数列表

ISOUND_PlayToneList()

说明：

此函数用于在指定的时间内播放给定音调 ID 的音调列表。

原型：

void ISOUND_PlayToneList
(
ISound * pISound,
AEESoundToneData * pToneData,
uint16 wDataLen
)

参数：

pISound | 指向 ISound 接口对象的指针。
pToneData | AEESoundToneData 结构列表（数组），其中每个结构都包含要播放的音调 ID 和播放时间（毫秒）。
wDataLen | pToneData 列表中的音调数。

返回值：

无

备注：

调用 ISOUND_StopTone() 可以结束播放音调列表。 如果列表中某个音调的播放时间设置为 0（零），则该音调将播放到调用 ISOUND_StopTone() 为止。

副作用：

对于列表中的每个音调，操作结果将通过回调函数指针发送给客户端。 而且在操作完成后，将通过同一回调函数指针通知客户端。 可能的状态值如下：

AEE_SOUND_SUCCESS，在每次成功播放音调列表中的音调后都将收到此值。

AEE_SOUND_FAILURE，播放音调列表中的音调失败或音调列表播放结束。

AEE_SOUND_PLAY_DONE，

    • 对于音调列表中的每个音调，在完成音调播放或者
    • 被其它音调替换时，都将收到此值。

另请参阅：

AEESoundToneData

返回函数列表

ISOUND_RegisterNotify()

说明：

此函数用于注册状态回调函数。

原型：

void ISOUND_RegisterNotify
(
ISound * pISound,
PFNSOUNDSTATUS pfn,
const void * pUser
)

参数：

pISound | 指向 ISound 接口对象的指针。
pfn | 状态回调函数指针（如果不需要回调，可以是 NULL）。
pUser | 用于唯一关联/标识事务处理的用户数据。 ISound 不获取或处理该信息，如果不需要标识数据，则可以为 NULL。 同一数据指针与回调状态一起回传客户端，以关联事务处理。

返回值：

无

备注：

以下是函数及其回调状态类型的列表：

ISOUND_PlayTone | AEE_SOUND_STATUS_CB
ISOUND_PlayToneList | AEE_SOUND_STATUS_CB
ISOUND_PlayFreqTone | AEE_SOUND_STATUS_CB
ISOUND_StopTone | AEE_SOUND_STATUS_CB
ISOUND_Vibrate | AEE_SOUND_STATUS_CB
ISOUND_StopVibrate | AEE_SOUND_STATUS_CB
ISOUND_GetVolume | AEE_SOUND_VOLUME_CB
ISOUND_SetVolume | AEE_SOUND_STATUS_CB

上表还指出了通过回调函数发出的状态类型。 状态类型可以决定解释状态数据部分的方式。 状态可以指示操作状态或获取操作的查询结果。 有关该注册回调函数的效果，请参阅每个函数的说明。

另请参阅：

PFNSOUNDSTATUS

返回函数列表

ISOUND_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOUND_AddRef()

返回函数列表

ISOUND_Set()

说明：

此函数用于设置 ISound 接口对象的设备属性。 设备属性包括“设备”、“方法”、“Apath”、“耳机静音控制”和“话筒静音控制”。

原型：

int ISOUND_Set(ISound * pISound, const AEESoundInfo * pSoundInfo)

参数：

pISound | 指向 ISound 接口对象的指针。
pSoundInfo | 包含 ISound 设备属性的结构。

返回值：

如果已设置设备属性，则返回 SUCCESS。

如果一个或多个 AEESoundInfo 参数出错，则返回 EBADPARAM。

备注：

在调用 ISOUND_SetDevice() 之前，不会连接设备。

副作用：

如果“未”返回 SUCCESS，则 ISound 接口将保留原值。 如果是首次创建，则使用默认值。

另请参阅：

AEESoundInfo

ISOUND_Get()

返回函数列表

ISOUND_SetDevice()

说明：

此函数用于命令 ISound 连接指定的音频设备。 在任意时间点，连接且仅连接一个音频设备。 调用 ISOUND_Set() 函数可以指定该音频设备。

注意：当前版本 BREW 的 BREW Emulator 不支持此函数

原型：

void ISOUND_SetDevice(ISound * pISound)

参数：

pISound
指向 ISound 接口对象的指针。

返回值：

无

备注：

BREW 设备支持此函数，但 BREW Emulator 不支持。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUND_SUCCESS，如果成功连接到新的声音设备。

AEE_SOUND_FAILURE，如果连接新的声音设备失败。

另请参阅：

ISOUND_Set()

返回函数列表

ISOUND_SetVolume()

说明：

此函数用于设置 ISOUND_Set() 调用指定的设备/方法对所使用的音量。

原型：

void ISOUND_SetVolume(ISound * pISound, uint16 wVolume)

参数：

pISound | 指向 ISound 接口对象的指针。
wVolume | 设备/方法的新音量。

返回值：

无

备注：

音量范围从 0（零，最低）到 AEE_MAX_VOLUME（最高）。 在 BREW Emulator 中，音量呈线性增加。 这一点与目标设备不同。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的结果如下：

AEE_SOUND_SUCCESS，如果已成功设置新音量。

AEE_SOUND_FAILURE，如果设置新音量失败；仍使用原来的音量。

另请参阅：

ISOUND_Set()

返回函数列表

ISOUND_StopTone()

说明：

此函数用于停止当前音调或音调列表的播放。

原型：

void ISOUND_StopTone(ISound * pISound)

参数：

pISound
指向 ISound 接口对象的指针。

返回值：

无

备注：

在 BREW Emulator 中，如果振动是激活的，此函数还会停止振动音调。

副作用：

操作结果将通过回调函数指针发送给客户端。 而且在操作完成后，将通过同一回调函数指针通知客户端。 可能的状态值如下：

AEE_SOUND_SUCCESS，如果成功接受停止命令。 如果音调或音调列表播放是激活的，还会生成 AEE_SOUND_PLAY_DONE 回调。

AEE_SOUND_FAILURE，如果接受停止命令失败。

另请参阅：

ISOUND_Vibrate()

返回函数列表

ISOUND_StopVibrate()

说明：

此函数用于停止当前振动。

注意：当前版本 BREW 的 BREW Emulator 不支持此函数。 由于振动是通过播放音调进行模拟，因此通过 ISOUND_StopTone() 即可模拟此函数。 调用此函数可以停止由 ISOUND_PlayTone() 启动的音调播放。

原型：

void ISOUND_StopVibrate(ISound * pISound)

参数：

pISound
指向 ISound 接口对象的指针。

返回值：

无

备注：

此函数不会导致任何回调。

副作用：

在 BREW Emulator 中，调用此函数与调用 ISOUND_StopTone() 的结果相同。
因此，它可以停止正在进行的 ISOUND_PlayTone() 播放。

另请参阅：

ISOUND_Vibrate()

返回函数列表

ISOUND_Vibrate()

说明：

此函数可以使设备在指定的时间内振动，或振动到调用 ISOUND_StopVibrate() 为止。

注意：当前版本 BREW 的 BREW Emulator 不支持此函数。 由于振动是通过播放音调进行模拟，因此通过 ISOUND_PlayTone() 即可模拟此函数。 调用此函数可以停止由 ISOUND_PlayTone() 启动的音调播放。

原型：

void ISOUND_Vibrate(ISound * pISound, uint16 w6Duration)

参数：

pISound | 指向公共 ISound 接口对象的指针。
wDuration | 振动时间（毫秒）。

返回值：

无

备注：

此函数不会导致任何回调。

副作用：

在 BREW Emulator 中，调用此函数与调用 ISOUND_PlayTone() 播放示例音调的结果相同。 因此，它可以停止正在进行的 ISOUND_PlayTone() 播放，反之亦然。

另请参阅：

ISOUND_StopVibrate()

返回函数列表


ISoundPlayer 接口

ISoundPlayer 接口用于提供音频多媒体服务。 ISoundPlayer 支持 MIDI、MP3 和 QCP（QUALCOMM PureVoice 或 QCELP）格式。 有关 QCP 格式和相关 BREW SDK 工具的详细信息，请参阅 BREW SDK 用户指南。

创建 ISoundPlayer 实例

创建 ISoundPlayer 实例有两种方法：

  1. 以 AEECLSID_SOUNDPLAYER 作为 ClassID，调用 ISHELL_CreateInstance()。
  2. 将 AEEHandlerType 设置为 HTYPE_SOUND，MIME 字符串设置为：
    snd/midi（MIDI）、snd/mp3（MP3）或 snd/qcp（QCP 格式），调用 ISHELL_GetHandler()。 然后使用返回的 ClassID 调用 ISHELL_CreateInstance()。

ISoundPlayer 输入类型

您可以在 AEESoundPlayerInfo 结构中指定音频源（输入类型和数据），并使用 ISOUNDPLAYER_SetInfo() 进行设置。 ISoundPlayer 接口可以使用内存缓冲区 SDT_BUFFER 或文件 SDT_FILE 进行播放。 它不支持流播放，但可以使用 ISOUNDPLAYER_SetStream() 将 IAStream 与 ISoundPlayer 关联。 ISoundPlayer 将流中的所有数据读入缓冲区，然后播放缓冲区。

如果给定指向ISOUNDPLAYER_GetInfo() 的指针，AEESoundPlayerInfo 将返回当前音
频源。

注意：ISoundPlayer 正忙时不设置音频源。 ISoundPlayer 正忙是指它正在播放、执行命令或流化输入数据。 要了解 ISoundPlayer 是否正忙，可以调用：
int ISOUNDPLAYER_GetInfo(pISoundPlayer, NULL)；如果 ISoundPlayer 空闲，则返回 EIDLE，如果正忙，则返回 EITEMBUSY。

注意： 不建议使用 ISOUNDPLAYER_Set()。 请使用可以更好访问 ISoundPlayer 的 ISOUNDPLAYER_SetInfo()。

播放控制

ISoundPlayer 提供以下播放控制函数：

ISOUNDPLAYER_Play() | 播放 MIDI/MP3/QCP 文件
ISOUNDPLAYER_Stop() | 停止播放
ISOUNDPLAYER_Rewind() | 播放倒回 n 毫秒。 QCP 格式不支持此命令。
ISOUNDPLAYER_FastForward() | 快进播放 n 毫秒，QCP 格式不支持此命令。
ISOUNDPLAYER_Pause() | 暂停播放，QCP 格式不支持此命令。
ISOUNDPLAYER_Resume() | 恢复播放，QCP 格式不支持此命令。
ISOUNDPLAYER_SetTempo() | 设置 MIDI 的播放速度。 不适用于 MP3 和 QCP。
ISOUNDPLAYER_SetTune() | 设置当前 MIDI 播放的音高，以半音为增量。 不适用于 MP3 和 QCP

ISOUNDPLAYER_Play() 的优先级高于 ISOUNDPLAYER_GetTotalTime()。 每次只能激活一个 ISOUNDPLAYER_Play()， 调用其它ISOUNDPLAYER_Play() 之前必须停止当前播放。
任何时候只能激活 #4 至 #9（见上表）之间的一个命令。 如果命令失败，ISoundPlayer 将发送 AEE_SOUNDPLAYER_FAILURE。

回调通知

多数 ISoundPlayer API 的调用实际上是异步的。 如果应用程序要从 IsoundPlayer 接收状态和事件，则该应用程序必须使用 ISOUNDPLAYER_RegisterNotify() 注册回调通知函数。 ISoundPlayer 再通过该注册回调函数将状态和事件发送给用户应用程序。

ISoundPlayer 接口可调用五种回调函数。

AEE_SOUNDPLAYER_PLAY_CB

AEE_SOUNDPLAYER_STATUS_CB

AEE_SOUNDPLAYER_TIME_CB

AEE_SOUNDPLAYER_SOUND_CB

AEE_SOUNDPLAYER_VOLUME_CB

每种回调类型依次包含仅对各自有效的一组状态指示和数据。

例如，对于 AEE_SOUNDPLAYER_PLAY_CB，状态类型可以是：

AEE_SOUNDPLAYER_SUCCESS

AEE_SOUNDPLAYER_PAUSE

AEE_SOUNDPLAYER_RESUME

等等

如果数据存在，将通过指向 AEESoundPlayerCmdData 结构的 dwParam 参数在回调中返回数据。 否则 dwParam 为空。

在播放过程中，AEE_SOUNDPLAYER_PLAY_CB 每秒钟都将向小程序通知 AEE_SOUNDPLAYER_TICK_ UPDATE 状态， 小程序因此可以更新播放进度。

在倒回、快进、暂停或恢复之后，AEE_SOUNDPLAYER_PLAY_CB 回调函数的 dwParam 参数将指向当前播放位置（毫秒）。 同样，小程序可以此更新播放进度。 MIDI-MP3 播放器示例小程序中将会演示这些机制。

注册回调函数并非必不可少， 按照以下代码调用 ISOUNDPLAYER_RegisterNotify()，可选择不获取任何 ISoundPlayer 事件：

ISOUNDPLAYER_RegisterNotify(pISoundPlayer, NULL, NULL);

音频设备和音量控制

ISoundPlayer 在内部使用 ISound 实例设置音频设备参数 (ISOUNDPLAYER_SetSoundDevice()) 和设置/获得输出音量（ISOUNDPLAYER_SetVolume() 和 ISOUNDPLAYER_GetVolume()）。 您不必为这些操作创建 ISound 实例。

使用 ISoundPlayer 接口服务

  1. 以 AEECLSID_SOUNDPLAYER 为 ClassID，调用 ISHELL_CreateInstance() 创建 ISoundPlayer 对象。
  2. 调用 ISOUNDPLAYER_RegisterNotify() 注册 ISoundPlayer 回调函数。 ISoundPlayer 接口始终使用该回调函数将所有事件或状态变化通知小程序。
  3. 使用 ISOUNDPLAYER_SetInfo() 函数设置 MIDI/MP3/QCP 媒体源
    （文件或缓冲区）。 务必检查是否成功。
  4. 在小程序事件处理程序中，调用播放控制函数，如 ISOUNDPLAYER_GetTotalTime()、ISOUNDPLAYER_Play()。
  5. 退出前，一定要：
    1. 通过调用
      ISOUNDPLAYER_RegisterNotify(pISoundPlayer, NULL, NULL)
取消注册回调函数。
    1. 如果播放处于激活状态，请调用 ISOUNDPLAYER_Stop()。

要包含的头文件列表

需要以下头文件：

AEESoundPlayer.h

函数列表

该接口的函数包括：

ISOUNDPLAYER_AddRef()

ISOUNDPLAYER_FastForward()

ISOUNDPLAYER_GetInfo()

ISOUNDPLAYER_GetTotalTime()

ISOUNDPLAYER_GetVolume()

ISOUNDPLAYER_Pause()

ISOUNDPLAYER_Play()

ISOUNDPLAYER_RegisterNotify()

ISOUNDPLAYER_Release()

ISOUNDPLAYER_Resume()

ISOUNDPLAYER_Rewind()

ISOUNDPLAYER_Set()

ISOUNDPLAYER_SetInfo()

ISOUNDPLAYER_SetSoundDevice()

ISOUNDPLAYER_SetStream()

ISOUNDPLAYER_SetTempo()

ISOUNDPLAYER_SetTune()

ISOUNDPLAYER_SetVolume()

ISOUNDPLAYER_Stop()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISOUNDPLAYER_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOUNDPLAYER_Release()

返回函数列表

ISOUNDPLAYER_FastForward()

说明：

此函数用于发出快进当前 MIDI/MP3 播放的命令。

原型：

void ISOUNDPLAYER_FastForward
(
ISoundPlayer * pISoundPlayer,
uint32 dwTime
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
dwTime | 当前播放要快进的时间量（毫秒）。

返回值：

无

备注：

此命令对于 QCP 格式无效。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功，并且已接受快进命令。
AEE_SOUNDPLAYER_FAILURE | 失败，并且未接受快进命令。 可能播放未处于激活状态，或激活了其它命令。

快进到文件末尾时将结束当前音频播放，并触发 AEE_SOUNDPLAYER_DONE 播放回调。 如果播放是激活的，此 API 将触发 AEE_SOUNDPLAYER_FFORWARD 播放回调。 快进函数完成时，如果音频文件还未结束，则将触发 AEE_SOUNDPLAYER_RESUME 播放回调。

另请参阅：

无

返回函数列表

ISOUNDPLAYER_GetInfo()

说明：

此函数用于获取 ISoundPlayer 的当前音频源或状态。 该函数的状态可立即返回。

原型：

int ISOUNDPLAYER_GetInfo
(
ISoundPlayer * pISoundPlayer,
AEESoundPlayerInfo * pInfo
)

参数：

pISoundPlayer | [in] | 指向 ISoundPlayer 接口对象的指针。
pInfo | [out] | ISoundPlayer 的音频源。

返回值：

AEE_SUCCESS
音频源成功返回。
错误代码
如果 pInfo 不为 NULL，或者 pInfo 为 NULL 并返回以下值之一。
  • EITEMBUSY
ISoundPlayer 忙是指当前正在播放、执行命令或流化输入数据。
  • EIDLE
ISoundPlayer 空闲。

备注：

应用程序必须为 pInfo 分配内存。

另请参阅：

AEESoundPlayerInfo

ISOUNDPLAYER_SetInfo()

返回函数列表

ISOUNDPLAYER_GetTotalTime()

说明：

此函数用于发出计算指定 MP3/MIDI 输入源的播放总时间的命令。

原型：

void ISOUNDPLAYER_GetTotalTime(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

一次只能执行一个播放或获取时间总量命令。 播放命令将覆盖以前的播放或获取时间总量命令， 但获取时间总量命令不会中断播放命令。

此命令对于 QCP 格式无效。

副作用：

操作结果由 AEE_SOUNDPLAYER_TIME_CB 回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功获取播放时间总量
AEE_SOUNDPLAYER_FAILURE | 获取播放时间总量失败。 原因可能是激活了播放命令或其它获取时间总量的命令。
AEE_SOUNDPLAYER_DONE | 成功获取播放时间总量。 The 回调函数的 dwParam 参数指向 AEESoundPlayerCmdData 的dwTotalTime 参数，其中包含了当前时间 （毫秒）。
AEE_SOUNDPLAYER_ABORTED | 命令被 ISOUNDPLAYER_Play() 中断

另请参阅：

无

返回函数列表

ISOUNDPLAYER_GetVolume()

说明：

此函数用于获取当前播放设备和方法的音量。

原型：

void ISOUNDPLAYER_GetVolume(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

音量范围从 0（零，最低）到 AEE_MAX_VOLUME（最高）。

副作用：

操作结果由 AEE_SOUND_VOLUME_CB 回调函数指针发送到客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功获取音量值。 dwParam 指向 AEESoundPlayerCmdData，其中的 wVolume 包含当前音量。
AEE_SOUNDPLAYER_FAILURE | 获取音量值失败。

另请参阅：

AEESoundCmd

ISOUNDPLAYER_SetVolume()

返回函数列表

ISOUNDPLAYER_Pause()

说明：

此函数用于发出暂停当前 MIDI/MP3 播放的命令。

原型：

void ISOUNDPLAYER_Pause(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

此命令对于 QCP 格式无效。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功，并且接受暂停命令。
AEE_SOUNDPLAYER_FAILURE | 失败，并且未接受暂停命令。 可能播放未处于激活状态，或激活了其它命令。

如果播放是激活的，此例程将触发 AEE_SOUNDPLAYER_FFORWARD 播放回调。

另请参阅：

无

返回函数列表

ISOUNDPLAYER_Play()

说明：

此函数用于发出命令，以从 ISOUNDPLAYER_Set() 调用中指定的输入源播放 MIDI/MP3/QCP 音频。

原型：

void ISOUNDPLAYER_Play(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

一次只能执行一个播放或获取时间总量命令。 播放命令将覆盖以前的获取时间总量命令， 但获取时间总量命令不会中断播放命令。 如果播放当前处于激活状态，则不会接受新的播放命令。

副作用：

以 AEE_SOUNDPLAYER_PLAY_CB 注册的回调函数在播放过程中多次触发以指示当前播放事务的状态。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 已接受播放命令并开始播放。
AEE_SOUNDPLAYER_REWIND | 正在倒回。
AEE_SOUNDPLAYER_FFORWARD | 正在快进。
AEE_SOUNDPLAYER_PAUSE | 暂停播放。
AEE_SOUNDPLAYER_RESUME | 在执行暂停、倒回和快进处理后正在恢复播放。
AEE_SOUNDPLAYER_TEMPO | 已更新播放速度系数。
AEE_SOUNDPLAYER_TUNE | 已更新播放音调系数。
AEE_SOUNDPLAYER_AUDIO_SPEC | 提供 MIDI/MP3 的相关文件规格。 在 BREW Emulator 中，只返回文件类型。 该回调不适用于 QCP 格式。
AEE_SOUNDPLAYER_TICK_UPDATE | 每秒定期更新。
AEE_SOUNDPLAYER_DATA_ACCESS_DELAY | 数据存取延迟导致播放暂时延迟。
AEE_SOUNDPLAYER_ABORTED | 播放中断。
AEE_SOUNDPLAYER_DONE | 播放完成。
AEE_SOUNDPLAYER_FAILURE | 未接受播放命令。原因可能是处理音频输入时出错或激活了其它播放。

以下信息将通过回调函数的 AEE_SOUNDPLAYER_AUDIO_SPEC 状态参数 dwParam 进行传递。

:

如果是 MIDI/CMX | 指向 AEESoundPlayerMIDISpec 结构的指针。
如果是 MP3 | 指向 AEESoundPlayerMP3Spec 结构的指针。

另请参阅：

ISOUNDPLAYER_Set()

返回函数列表

ISOUNDPLAYER_RegisterNotify()

说明：

此函数用于注册状态事件回调函数。

原型：

void ISOUNDPLAYER_RegisterNotify
(
ISoundPlayer * pISoundPlayer,
PFNSOUNDPLAYERSTATUS pfn,
void * pUser
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
pfn | 指向用户回调的指针（NULL 用于注销）。
pUser | 用于唯一关联/标识事务处理的用户数据。 ISoundPlayer 不获取或处理该信息，如果不需要标识数据，可以为 NULL。 同一数据指针与回调状态一起回传客户端，以关联事务处理。

返回值：

无

备注：

以下是函数及其回调状态类型的列表：

ISOUNDPLAYER_Play | AEE_SOUNDPLAYER_PLAY_CB
ISOUNDPLAYER_Stop | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_Rewind | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_FastForward | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_Pause | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_Resume | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_SetTempo | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_SetTune | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_SetVolume | AEE_SOUNDPLAYER_STATUS_CB
ISOUNDPLAYER_GetVolume | AEE_SOUNDPLAYER_VOLUME_CB
ISOUNDPLAYER_GetTotalTime | AEE_SOUNDPLAYER_TIME_CB
ISOUNDPLAYER_SetSoundDevice | AEE_SOUNDPLAYER_STATUS_CB

上表还指出了通过回调函数发回的状态类型。 状态类型可以决定解释状态数据部分的方式。 状态可以指示操作状态或获取操作的查询结果。 有关该注册回调函数的效果，请参阅每个函数的说明。

注意：通过发出以下调用，应用程序可以选择不注册回调：

ISOUNDPLAYER_RegisterNotify(pISoundPlayer, NULL, NULL);

另请参阅：

PFNSOUNDPLAYERSTATUS

返回函数列表

ISOUNDPLAYER_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOUNDPLAYER_AddRef()

返回函数列表

ISOUNDPLAYER_Resume()

说明：

此函数用于发出恢复当前 MIDI/MP3 播放的命令。

原型：

void ISOUNDPLAYER_Resume(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

必须已经使用 ISOUNDPLAYER_Pause() 函数暂停播放。

如果当前未使用 ISOUNDPLAYER_Pause() 函数暂停播放，则此函数调用无效。

此命令对于 QCP 格式无效。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功，并且接受恢复命令
AEE_SOUNDPLAYER_FAILURE | 失败，并且未接受恢复命令。 可能播放未处于激活状态，或激活了其它命令。

如果播放处于激活状态，此例程将触发 AEE_SOUNDPLAYER_RESUME 播放回调。

另请参阅：

ISOUNDPLAYER_Pause()

返回函数列表

ISOUNDPLAYER_Rewind()

说明：

此函数用于发出倒回当前 MIDI/MP3 播放的命令。

原型：

void ISOUNDPLAYER_Rewind(ISoundPlayer * pISoundPlayer, uint32 dwTime)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
dwTime | 当前播放要倒回的时间量（毫秒）。

返回值：

无

备注：

此命令对于 QCP 格式无效。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功，并且接受倒回命令。
AEE_SOUNDPLAYER_FAILURE | 失败，并且未接受倒回命令。 可能播放未处于激活状态，或激活了其它命令。

如果倒回到音频文件的开始处，则将从头播放。 如果播放处于激活状态，此例程将触发 AEE_SOUNDPLAYER_REWIND 播放回调。 倒回函数完成后，将触发 AEE_SOUNDPLAYER_RESUME 播放回调。

另请参阅：

无

返回函数列表

ISOUNDPLAYER_Set()

注意：建议不使用此函数， 而使用 ISOUNDPLAYER_SetInfo()。

说明：

此函数用于释放前一输入数据缓冲区的内存（如果有），并将当前的输入数据缓冲区设置为 MIDI/MP3/QCP 音频源。

注意：当前版本 BREW 不支持 SDT_VOICEPROMPT 输入源。

原型：

void ISOUNDPLAYER_Set
(
ISoundPlayer * pISoundPlayer,
AEESoundPlayerInput t,
void * pData
)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。
t
pData 的源类型。 支持的值包括：
  • SDT_FILE： 指定数据为文件名。
  • SDT_BUFFER： 指定数据为原始缓冲区。
pData
指定类型的数据指针。

返回值：

无

备注：

注意：BREW Emulator 仅支持 SDT_FILE。

副作用：

如果输入类型为 SDT_FILE，则 ISoundPlayer 将把文件名从 pData 复制到它的本地缓冲区。 应用程序负责释放分配给 pData 的内存。

如果输入类型为 SDT_BUFFER，则 ISoundPlayer 不复制自身，但会使用指向应用程序分配的缓冲区的 pData 指针。 ISoundPlayer 将在其它 ISOUNDPLAYER_Set() 调用或最后一个 ISOUNDPLAYER_Release() 调用之后释放该内存。 应用程序不会释放此内存。

另请参阅：

AEESoundPlayerInput

返回函数列表

ISOUNDPLAYER_SetInfo()

说明：

此函数用于设置或重置 ISoundPlayer 的音频源。 该函数的状态可立即返回。

原型：

int ISOUNDPLAYER_SetInfo
(
ISoundPlayer * pISoundPlayer,
AEESoundPlayerInfo * pInfo
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
pInfo | ISoundPlayer 的音频源。

返回值：

AEE_SUCCESS，如果 pInfo 不为 NULL，已成功设置音频源，或者 pInfo 为 NULL，已成功重置音频源。

错误代码：

如果 ISoundPlayer 正忙，则返回 EITEMBUSY。 ISoundPlayer 忙是指当前正在播放、执行命令或流化输入数据。

如果函数遇到错误参数（例如将 pInfo -> dwSize 设置为零），则返回 EBADPARM。

如果当前版本 BREW 不支持该输入类型，则返回 EUNSUPPORTED。

备注：

如果 pInfo 为 NULL，成功执行此函数将使 ISoundPlayer 释放为前一个音频源分配的内存。 应用程序将负责释放分配给 pInfo -> pData 的内存。

副作用：

如果成功设置音频源，则将释放由 ISoundPlayer 为前一音频源分配的内存。 如果输入类型为 SDT_FILE，ISoundPlayer 将把文件名从 pInfo -> pData 复制到它的本地缓冲区。

另请参阅：

AEESoundPlayerInfo

ISOUNDPLAYER_GetInfo()

返回函数列表

ISOUNDPLAYER_SetSoundDevice()

说明：

此函数用于命令设备连接指定的音频设备。 在任意时间点，连接且仅连接一个音
频设备。

原型：

void ISOUNDPLAYER_SetSoundDevice
(
ISoundPlayer * pISoundPlayer,
AEESoundDevice eDevice,
AEESoundMuteCtl eEarMute,
AEESoundMuteCtl eMicMute
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
eDevice | 要连接的音频设备。
eEarMute | 耳机静音或非静音。
eMicMute | 话筒静音或非静音。

返回值：

无

备注：

注意： 当前版本 BREW 的 BREW Emulator 不支持此函数，但 BREW 设备支持此
函数。

副作用：

操作结果将通过 AEE_SOUNDPLAYER_SOUND_CB 回调函数指针发送到客户端。
可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功连接新的声音设备
AEE_SOUNDPLAYER_FAILURE | 连接新的声音设备失败。 可能其它命令处于激活状态。

另请参阅：

AEESoundMuteCtl

AEESoundDevice

返回函数列表

ISOUNDPLAYER_SetStream()

说明：

此函数允许 IAStream 接口与 ISoundPlayer 实例相关联，使音频源数据（如文件或套接字）可以从 IAStream 流化。

原型：

void ISOUNDPLAYER_SetStream
(
ISoundPlayer * pISoundPlayer,
IAStream * ps
)

参数：

pISoundPlayer | 指向接收音频输入流的 ISoundPlayer 接口对象的指针。
ps | 实现 IAStream 接口（例如，IFile 或 ISocket 接口）的类的实例指针。

返回值：

无

备注：

ISOUNDPLAYER_SetStream() 仅支持来自 TCP 套接字的网络流，不支持来自 UDP 套接字的网络流。

ISoundPlayer 将全部流读入缓冲区，并在内部使用 SDT_BUFFER 作为输入类型。

副作用：

如果 ISoundPlayer 不忙，则将释放分配给前一音频源的内存（由 ISoundPlayer
分配）。

该函数将异步触发 AEE_SOUNDPLAYER_STATUS 回调。 状态列表包括：

AEE_SOUNDPLAYER_SUCCESS | 成功完成音频源数据的流化。
AEE_SOUNDPLAYER_FAILURE | 音频源数据流化失败。 原因可能是 ISoundPlayer 繁忙或流化出错。

如果流化成功，ISoundPlayer 将为缓冲区内部分配内存，并将音频源类型设置为 SDT_BUFFER。 应用程序无需考虑内存。

另请参阅：

IASTREAM_Read()

IASTREAM_Readable()

返回函数列表

ISOUNDPLAYER_SetTempo()

说明：

此函数用于发出将当前 MIDI 的播放速度修改为正常播放速度一定百分比的命令。

原型：

void ISOUNDPLAYER_SetTempo
(
ISoundPlayer * pISoundPlayer,
uint32 dwTempoFactor
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
dwTempoFactor | 该参数用于将播放速度修改为正常播放速度一定的百分比。 可能播放未处于激活状态，或激活了其它命令。 dwTempoFactor 为 50 表示正常播放速度的一半。 支持的最大速度系数是 500%，即正常播放速度的五倍。 最小的速度系数是正常播放速度的 1%。 调用 ISOUNDPLAYER_Play() 函数时，初始速度系数是 100%。

返回值：

无

备注：

注意： 当前版本 BREW 的 BREW Emulator 不支持此函数，但目标设备支持此函数。

此函数不适用于 MP3 和 QCP 格式。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功设置新的速度值
AEE_SOUNDPLAYER_FAILURE | 设置新的速度值失败；原值保留

如果播放处于激活状态，此例程将触发 AEE_SOUNDPLAYER_TEMPO 播放回调。

另请参阅：

ISOUNDPLAYER_Play()

返回函数列表

ISOUNDPLAYER_SetTune()

说明：

此函数用于发出修改当前 MIDI 播放音质（音高）的命令，并以半音为增量。

注意： 当前版本 BREW 的 BREW Emulator 不支持此函数，但 BREW 设备支持此
函数。

原型：

void ISOUNDPLAYER_SetTune(ISoundPlayer * pISoundPlayer, uint8 nStep)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
nStep | 该参数用于修改播放的音高，并以半音为增量。 例如，音高系数为 0 指示正常播放； 音高系数为 1 则指示比正常播放高半音。 支持的增量值从 -12 至 12， 即最高音高可以比正常播放高八度，最低音高则比正常播放低八度。 该参数用于将播放音高修改为正常播放的一定百分比。

返回值：

无

备注：

此函数用于命令 ISoundPlayer 修改当前 MIDI 播放的音高，并以半音为增量，其中 0x40 表示正常播放。

示例：

  • 音高系数为 0x40 表示正常播放。
  • 音高系数为 0x3F 表示以低于正常音高半个音播放。
  • 音高系数为 0x41 表示以高于正常音高半个音播放。
  • 音高系数为 0x34 表示以低于正常音高 12 个半音或 1 个八度播放。
  • 音高系数为 0x4C 表示以高于正常音高 12 个半音或 1 个八度播放。

支持的最高音高系数为 0x4C，即比正常音高高 1 个八度音。 支持的最低音高系数为 0x34，即比正常音高低 1 个八度音。 对于每一个新的 ISOUNDPLAYER_Play()，其音高系数将重置为 0x40 或正常。

该命令不适用于 MP3 和 QCP 格式。

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功设置新的音高值
AEE_SOUNDPLAYER_FAILURE | 设置新的音高失败，原值保留

如果播放处于激活状态，此例程将触发 AEE_SOUNDPLAYER_TUNE 播放回调。

另请参阅：

ISOUNDPLAYER_Play()

返回函数列表

ISOUNDPLAYER_SetVolume()

说明：

此函数用于设置当前播放设备的音量。

原型：

void ISOUNDPLAYER_SetVolume
(
ISoundPlayer * pISoundPlayer,
uint16 wVolume
)

参数：

pISoundPlayer | 指向 ISoundPlayer 接口对象的指针。
wVolume | 设备/方法新的音量。

返回值：

无

备注：

音量范围从 0（零，最低）到 AEE_MAX_VOLUME（最高）。

副作用：

操作结果将通过 AEE_SOUNDPLAYER_SOUND_CB 回调函数指针发送到客户端。
可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功设置新的音量值
AEE_SOUNDPLAYER_FAILURE | 设置新的音量值失败; 原值保留

另请参阅：

ISOUNDPLAYER_GetVolume()

返回函数列表

ISOUNDPLAYER_Stop()

说明：

此函数用于发出停止当前 MIDI/MP3/QCP 播放的命令。

原型：

void ISOUNDPLAYER_Stop(ISoundPlayer * pISoundPlayer)

参数：

pISoundPlayer
指向 ISoundPlayer 接口对象的指针。

返回值：

无

备注：

无

副作用：

操作结果将通过回调函数指针发送给客户端。 可能的状态值如下：

AEE_SOUNDPLAYER_SUCCESS | 成功，并且接受停止指令。
AEE_SOUNDPLAYER_FAILURE | 失败，并且未接受停止命令。

如果该操作成功，此函数还将为播放处理触发其它事件，以用 AEE_SOUNDPLAYER_DONE 值将其发往客户端。

另请参阅：

无

返回函数列表


ISource 接口

提供 Read/Readable 接口的抽象数据源。

要包含的头文件列表

需要以下头文件：

AEESource.h

函数列表

该接口的函数包括：

ISOURCE_AddRef()

ISOURCE_Exhausted()

ISOURCE_Read()

ISOURCE_Readable()

ISOURCE_Release()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISOURCE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOURCE_Release()

返回函数列表

ISOURCE_Exhausted()

说明：

此函数用于确定 ISource/IPeek/IGetLine 是否用尽数据。

定义：

ISOURCE_Exhausted(code)((unsigned) - (code) < 2U)

参数：

code
从 Read()、Peek() 或 GetLine() 返回的值

返回值：

如果源数据已用尽（无更多数据），则返回 TRUE

否则，返回 FALSE。

备注：

如果是 Peek() 和 GetLine()，可能仍然存在返回的数据。 请检查 _Peek() 的 cbAvailable 参数或 GetLine 数据结构的 nLen 字段。

另请参阅：

无

返回函数列表

ISOURCE_Read()

说明：

此函数用于将源数据流中的字节复制到指定缓冲区。 复制的所有字节均“用尽”（即，“读指针”前置）。

原型：

int ISOURCE_Read(ISource * pISource, char * pc, int cb)

参数：

pISource | 指向 ISource 接口对象的指针。
pc | 指向接收所读字节的缓冲区的指针。
cb | pc 的大小

-> char *pc: 指向接收所读字节的缓冲区的指针

-> int cb: sizeof(pc)

返回值：

如果成功，则返回读取的字节数。

否则，返回错误代码。

ISOURCE_END，对等端正常切断连接（无更多数据）。

ISOURCE_ERROR，遇到错误（无更多数据）。

ISOURCE_WAIT，此时无可用数据；调用 Readable() 以等待。

备注：

ISOURCE_WAIT 返回值用于取代错误返回值和 EWOULDBLOCK 错误代码。

另请参阅：

无

返回函数列表

ISOURCE_Readable()

说明：

当 IGETLINE_Read() 返回 IGETLINE_WAIT 之外的其它值时，调度或取消要调用的
回调。

原型：

void ISOURCE_Readable(ISource *pISource, AEECallback *pcb)

参数：

pISource | 指向 ISource 接口对象的指针。
pcb | 当 ISource 可读时，指向调用位置的指针。

返回值：

无

备注：

ISOURCE_WAIT 返回值用于取代错误返回值和 EWOULDBLOCK 错误代码。

另请参阅：

无

返回函数列表

ISOURCE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOURCE_AddRef()

返回函数列表


ISourceUtil 接口

此接口用于构造常用的源。

要包含的头文件列表

需要以下头文件：

AEESource.h

函数列表

该接口的函数包括：

ISOURCEUTIL_AddRef()

ISOURCEUTIL_AStreamFromSource()

ISOURCEUTIL_GetLineFromSource()

ISOURCEUTIL_PeekFromMemory()

ISOURCEUTIL_PeekFromSource()

ISOURCEUTIL_Release()

ISOURCEUTIL_SourceFromAStream()

ISOURCEUTIL_SourceFromMemory()

ISOURCEUTIL_SourceFromSocket()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISOURCEUTIL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOURCEUTIL_Release()

返回函数列表

ISOURCEUTIL_AStreamFromSource()

说明：

此函数用于生成从 ISource 接口对象获取数据的新 IAStream 接口对象。

原型：

int32 ISOURCEUTIL_AStreamFromSource
(
ISourceUtil *pISourceUtil,
ISource *pis,
IAStream **ppias
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pis | [in] | 要读取的数据源。
ppias | [out] | 指向将填入所生成 IAStream 接口对象的接口指针的 指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 IAStream 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

ISOURCEUTIL_SourceFromAStream()

返回函数列表

ISOURCEUTIL_GetLineFromSource()

说明：

此函数用于生成从 ISource 接口对象获取数据的新 IGetLine 接口对象。

原型：

int32 ISOURCEUTIL_GetLineFromSource
(
ISourceUtil *pISourceUtil,
ISource *pirs,
int32 nBufSize,
IGetLine **ppips
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pirs | [in] | 数据源。
nBufSize | [in] | 尝试为缓冲分配的内存量，应与读取的数据相关。
ppips | [out] | 指向将填入所生成 IGetLine 接口对象的接口指针的 指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 IGetLine 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

无

ISOURCEUTIL_PeekFromMemory()

返回函数列表

ISOURCEUTIL_PeekFromMemory()

说明：

此函数用于生成从内存块获取数据的新 IPeek 接口对象。

原型：

int32 ISOURCEUTIL_PeekFromMemory
(
ISourceUtil *pISourceUtil,
const void *pBuf,
int32 nBufLen,
PFNNOTIFY pUserFreeFn,
void *pUserFreeData,
IPeek **ppip
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pBuf | [in] | 数据缓冲区。
nBufLen | [in] | pBuf 中的字节数。
pUserFreeFn | [in] | 完成读取内存时的调用位置，可以是 NULL。
pUserFreeData | [in] | 用于调用 pUserFreeFn 的数据。
ppip | [out] | 指向将填入所生成 IPeek 接口对象的接口指针的指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 IPeek 接口对象，则返回 ENOMEMORY。

备注：

如果使用只读内存创建 IPeek 接口对象，则要注意不可修改 IPEEK_Peek() 返回的缓冲数据。

另请参阅：

ISOURCEUTIL_SourceFromAStream()

返回函数列表

ISOURCEUTIL_PeekFromSource()

说明：

此函数用于生成从 ISource 接口对象获取数据的新 IPeek 接口对象。

原型：

int ISOURCEUTIL_PeekFromSource
(
ISourceUtil * pISourceUtil,
ISource * pirs,
int32 nBufSize,
IGetLine * * ppips
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pirs | [in] | 作为数据源的 ISource 接口对象。
nBufSize | [in] | 尝试为缓冲分配的内存量，应与读取的数据相关。
ppips | [in/out] | 指向将填入所生成 IPeek 接口对象的接口指针的指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 IPeek 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

无

返回函数列表

ISOURCEUTIL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISOURCEUTIL_AddRef()

返回函数列表

ISOURCEUTIL_SourceFromAStream()

说明：

此函数用于生成从 IAStream 接口对象获取数据的新 ISource 接口对象。

原型：

int32 ISOURCEUTIL_SourceFromAStream
(
ISourceUtil *pISourceUtil,
IAStream *pias,
ISource **ppis
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pias | [in] | 读取的 IAStream 接口对象。
ppis | [out] | 指向将填入所生成 ISource 接口对象的接口指针的 指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 ISource 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

ISOURCEUTIL_AStreamFromSource()

返回函数列表

ISOURCEUTIL_SourceFromMemory()

说明：

此函数用于生成从内存块获取数据的新 ISource 接口对象。

原型：

int ISOURCEUTIL_SourceFromMemory
(
ISourceUtil * pISourceUtil,
const void * pBuf,
int32 nBufLen,
PFNNOTIFY pUserFreeFn,
void * pUserFreeData,
ISource * * ppis
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
pBuf | [in] | 数据缓冲区。
nBufLen | [in] | pBuf 中的字节数。
pUserFreeFn | [in] | 完成读取内存时的调用位置，可以是 NULL。
pUserFreeData | [in] | 用于调用 pUserFreeFn 的数据。
ppirs | [in/out] | 指向将填入所生成 ISource 接口对象的接口指针的 指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 ISource 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

PFNNOTIFY

FREE()

返回函数列表

ISOURCEUTIL_SourceFromSocket()

说明：

此函数用于生成从 ISocket 接口对象获取数据的新 ISource 接口对象。

原型：

int ISOURCEUTIL_SourceFromSocket
(
ISourceUtil * pISourceUtil,
ISocket * ps,
ISource * * ppirs
)

参数：

pISourceUtil | [in] | 指向 ISourceUtil 接口对象的指针。
ps | [in] | 读取的 ISocket 接口对象。
ppirs | [out] | 指向将填入所生成 ISource 接口对象的接口指针的 指针。

返回值：

如果成功，则返回 SUCCESS。

如果函数不能生成新的 ISource 接口对象，则返回 ENOMEMORY。

备注：

无

另请参阅：

无

返回函数列表


ISprite 接口

说明：

ISprite 接口用于渲染 sprite 和 tile 贴图。 Sprite 是关联了各种附加属性的位图。 这些属性包括绘制 sprite 的位置、变换和透明色等。 Sprite 非常适用于在游戏程序中绘制屏幕内移动的动画人物和对象。 可以使用 ISPRITE_DrawSprites() 函数绘制 Sprite，使用 ISPRITE_SetSpriteBuffer() 设置包含 sprite 图像的位图。 Tile 贴图可以视为位图 (tile) 的二维矩阵，这些位图尺寸相同，绘制时相互之间不留空间。 Tile 贴图可以表示为索引数组。 数组中的位置确定绘制 tile 的位置，而数组中该位置存储的索引则确定将要绘制的 tile。 此外，不仅每个 tile 位置都有关联的附加属性（例如透明色和简单变换），整个 tile 贴图也有关联属性（例如绘制偏移量、tile 大小和包装）。 Tile 贴图非常适用于在游戏程序中绘制背景。 小的 tile 集可以用来创建大的和复杂的贴图或背景。

可以使用 ISPRITE_DrawTiles() 函数绘制 tile 贴图，使用 ISPRITE_SetSpriteBuffer() 设置包含 tile 集的位图。ISPRITE_SetTransformTable() 可设置用来对 sprite 应用任意仿射变换的表。

ISPRITE_SetDestination() 可设置用于所有绘制操作的目标位图。

要包含的头文件列表

需要以下头文件：

AEESprite.h

函数列表

此接口的函数包括：

ISPRITE_AddRef()

ISPRITE_DrawSprites()

ISPRITE_DrawTiles()

ISPRITE_QueryInterface()

ISPRITE_Release()

ISPRITE_SetDestination()

ISPRITE_SetSpriteBuffer()

ISPRITE_SetTileBuffer()

ISPRITE_SetTransformTable()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISPRITE_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISPRITE_Release()

返回函数列表

ISPRITE_DrawSprites()

说明：

此函数用于绘制 pCmds 数组中的 sprite。 Sprite 引擎将按顺序遍历该数组四次。 第一遍仅绘制 unLayer 字段设为 0 的 sprite。后续几遍将分别绘制 1、2 和 3 层。 该数组以 unSpriteSize 设为 SPRITE_SIZE_END 的虚拟条目结束。 所有 sprite 都绘制到 ISPRITE_SetDestination() 指定的位图中。

原型：

int ISPRITE_DrawSprites(ISprite *pISprite, AEESpriteCmd *pCmds);

参数：

pISprite | 指向 ISprite 接口的指针。
pCmds | Sprite 命令数组。

返回值：

如果成功，则返回 SUCCESS。

如果 pCmd 为 NULL，则返回 EBADPARM。

备注：

无

另请参阅：

ISPRITE_SetDestination()

ISPRITE_SetTransformTable()

AEESpriteCmd

返回函数列表

ISPRITE_DrawTiles()

说明：

此函数用于绘制 pMaps 数组中的 tile 贴图。 数组中的每个条目说明一个 tile 贴图。 Sprite 引擎将按顺序遍历该数组一次。 该数组以 pMapArray 字段设为 NULL 的虚拟条目结束。 所有 tile 将绘制到 ISPRITE_SetDestination() 指定的位图中。

原型：

int ISPRITE_DrawTiles(ISprite *pISprite, AEETileMap *pMaps);

参数：

pISprite | 指向 ISprite 接口的指针。
pMaps | Tile 贴图数组。

返回值：

如果成功，则返回 SUCCESS。

如果 pMap 为 NULL，则返回 EBADPARM。

备注：

无

另请参阅：

ISPRITE_SetDestination()

AEETileMap

返回函数列表

ISPRITE_QueryInterface()

说明：

此函数检索指向符合指定类 ID 定义的接口的指针。它可用于查询扩展功能，如未来版本或专有功能。 查询成功时，将返回一个增加的接口实例。 调用程序负责在将来调用 Release()。 返回指针不是接口指针的情况除外。 在这种情况下，内存与正被查询的对象具有相同的使用期，所返回的指针将不用于释放对象。

原型：

int ISPRITE_QueryInterface(ISprite *pISprite, AEECLSID id, void **p);

参数：

pISprite | [in] | 指向 ISprite 接口的指针。
id | [in] | 标识正在尝试查询的实体（接口或数据）的全局唯一 id。
p | [out] | 指向要检索的数据或接口的指针。 如果传递回来的值为 NULL，则表示要查询的接口或数据不存在。

返回值：

如果成功，则返回 SUCCESS，

否则，将返回错误代码。

备注：

如果失败，*pISprite 将设置为 NULL。但最好在调用 QueryInterface() 之前将 *pISprite 明确设置为 NULL。

注意：此函数当前仅响应 AEECLSID_SPRITE。

另请参阅：

无

返回函数列表

ISPRITE_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISPRITE_AddRef()

返回函数列表

ISPRITE_SetDestination()

说明：

此函数用于告知 sprite 引擎渲染 sprite 和 tile 的位置。ISPRITE_DrawSprites()
和 ISPRITE_DrawTiles() 均将此位图作为目标。 传递值为 NULL 的 pbmDst，将强制 sprite 引擎释放现有的目标位图。

原型：

int ISPRITE_SetDestination(ISprite *pISprite, IBitmap *pbmDst);

参数：

pISprite | 指向 ISprite 接口的指针。
pbmDst | 用作绘制操作目标的位图。

返回值：

如果成功，则返回 SUCCESS。注意：在本版本中，该函数总是返回SUCCESS。

备注：

Sprite 引擎将相应地对位图调用 ISPRITE_AddRef() 和 ISPRITE_Release()。 这样，
调用程序就不必对该位图调用释放函数。 Sprite 引擎处理完位图后，将释放该位图。 目标位图必须支持 ITransform 接口，以便应用任何类型的变换。 通常，目标位图为设备位图或其它与设备位图兼容的位图。

另请参阅：

ISPRITE_DrawSprites()

ISPRITE_DrawTiles()

返回函数列表

ISPRITE_SetSpriteBuffer()

说明：

此函数用于告知 sprite 引擎查找特定大小 sprite 图像的位置。 Sprite 引擎可以为各种 sprite 大小维护单独的缓冲区。 位图缓冲区中包含的 sprite 图像以单列方式排列。 AEESpriteCmd 的 unSpriteIndex 字段值为 0 指代缓冲区中的第一个图像。 对于 16x16 sprite，索引 0 指代左上角位于 (0, 0) 的 16x16 正方形。 索引 1 指代左上角位于 (0, 16) 的 16x16 正方形。 传递值为 NULL 的 pbmSpriteBuffer，将强制 sprite 引擎释放现有的 sprite 缓冲区。

原型：

int ISPRITE_SetSpriteBuffer
(
ISprite *pISprite,
uint8 unSpriteSize,
IBitmap *pbmSpriteBuffer
)

参数：

pISprite | 指向 ISprite 接口的指针。
unSpriteSize | 缓冲区中 sprite 的大小。 对应于 AEESpriteCmd 的 unSpriteSize 字段。
pbmSpriteBuffer | 用于 sprite 缓冲区的位图。

返回值：

如果成功，则返回 SUCCESS。

如果 unSpriteSize 无效，则返回 EBADPARM。

备注：

Sprite 引擎将相应地对位图调用 ISPRITE_AddRef() 和 ISPRITE_Release()。 这样，
调用程序就不必对该位图调用 ISPRITE_Release()。 Sprite 引擎处理完位图后，将释放该位图。 Sprite 缓冲区应与目标位图具有相同的位图类型。

另请参阅：

ISPRITE_SetTileBuffer()

ISPRITE_DrawSprites()

AEESpriteCmd

返回函数列表

ISPRITE_SetTileBuffer()

说明：

此函数用于告知 sprite 引擎查找特定大小 tile 图像的位置。 Sprite 引擎可以为各种 tile 大小维护单独的缓冲区。 与 sprite 缓冲区类似，tile 在位图缓冲区中以单列方式排列。 与 sprite 索引可用于查找 sprite 类似，tile 索引也可以用来查找 tile。 传递值为 NULL 的 pbmTileBuffer，将强制 sprite 引擎释放现有的 tile 缓冲区。

原型：

int ISPRITE_SetTileBuffer
(
ISprite *pISprite,
uint8 unTileSize,
IBitmap *pbmTileBuffer
)

参数：

pISprite | 指向 ISprite 接口的指针。
unTileSize | 缓冲区中 tile 的大小。 对应于 AEETileMap 的 unTileSize 字段。
pbmTileBuffer | 用于 tile 缓冲区的位图。

返回值：

如果成功，则返回 SUCCESS。

如果 unSpriteSize 无效，则返回 EBADPARM。

备注：

Sprite 引擎将相应地对位图调用 ISPRITE_AddRef() 和 ISPRITE_Release()。 这样，
调用程序就不必对该位图调用释放函数。 Sprite 引擎处理完位图后，将释放该位图。 Tile 缓冲区应与目标位图具有相同的位图类型。

另请参阅：

ISPRITE_SetSpriteBuffer()

ISPRITE_DrawTiles()

AEETileMap

返回函数列表

ISPRITE_SetTransformTable()

说明：

此函数用于告知 sprite 引擎查找已设置 SPRITE_MATRIX_TRANSFORM 属性的 sprite 变换的位置。 AEESpriteCmd 的 unMatrixTransform 字段指定所使用的表条目。

原型：

int ISPRITE_SetTransformTable
(
ISprite *pISprite,
AEETransformMatrix *pTransformTable
)

参数：

pISprite | 指向 ISprite 接口的指针。
pTransformTable | AEETransformMatrix 结构的数组。

返回值：

如果成功，则返回 SUCCESS。注意：在本版本中，该函数总是返回SUCCESS。

备注：

Sprite 引擎不会复制该表，也不会尝试释放该表。 调用程序负责在适当的时间释放表内存。

另请参阅：

ISPRITE_DrawSprites()

AEESpriteCmd

返回函数列表


ISSL 接口

此接口可以为网络连接提供 SSL/TLS 安全。 它继承于 WebOpt， 并在接口中使用 ISocket。
请注意，此功能可与 http 结合，在 IWeb 接口中形成HTTPS。 在此处和 IX509Chain 中说明的 web 选项均可应用于HTTPS。

要包含的头文件列表

需要以下头文件：

AEESSL.h

函数列表

此接口的函数包括：

ISSL_AddOpt()

ISSL_AddRef()

ISSL_Close()

ISSL_GetOpt()

ISSL_Negotiate()

ISSL_NegotiateV()

ISSL_QueryInterface()

ISSL_Release()

ISSL_RemoveOpt()

ISSL_Renegotiate()

ISSL_RenegotiateV()

ISSL_SetSocket()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISSL_AddOpt()

说明：

此函数继承于 IWEBOPTS_AddOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

WebOpt

ISSL_RemoveOpt()

ISSL_GetOpt()

返回函数列表

ISSL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISSL_Release()

返回函数列表

ISSL_Close()

说明：

此函数用于关闭 SSL 会话。

原型：

void ISSL_Close(ISSL *pISSL, SSLInfo *pinfo, AEECallback *pcb);

参数：

pISSL | 接口指针
pinfo | 放置响应结构的位置
pcb | SSL 成功、失败或需要帮助时回调的位置

返回值：

如果 SSLInfo 中返回 nReturn，则表示关闭成功

备注：

ISSL_Close() 尝试向服务器发送关闭通知警告。

实际使用的 SSL 关闭与文档说明的标准会有所不同。 标准要求完全交换关闭警告。
而在实践中，可以通过交换属于安全协议一部分的协议消息（而非 SSL）来实现安全关闭。 HTTP 正是如此。 完全关闭基本上不必要，因此此处的实现只是尝试发送关闭通知，而不是完全关闭握手。

另请参阅：

SSLInfo

SSLSecurityInfo

X509TrustResult

返回函数列表

ISSL_GetOpt()

说明：

此函数继承于 IWEBOPTS_GetOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表

WebOpt

ISSL_AddOpt()

ISSL_RemoveOpt()

返回函数列表。

ISSL_Negotiate()

说明：

此函数将用于进行 SSL 握手。 如果握手尚未开始，它将启动握手。 如果握手正在进行，它将继续此握手。 如果已建立握手，它将报告与请求相关的握手状态。

原型：

void ISSL_Negotiate
(
ISSL *pISSL,
SSLInfo *pinfo,
IX509Chain **pCerts,
AEECallback *pcb,
...)

参数：

pISSL | 接口指针
pinfo | 放置响应结构的位置
IX509Chain **pCerts | ISSL 返回证书链的位置
... | 执行协商所依据的选项集

返回值：

无

备注：

在最简单的情况下，此调用将一直进行协商，直至协商完成或失败。 它使用命令行所传递的选项以及实例中存储的所有选项作为协商参数。 该协商还使用 IX509Chain 实例在内部对证书链进行验证。 协商完成或失败时将填写 pinfo 并调用回调。

评估协商参数时应首先考虑命令行所传递的选项。 请注意，这些选项可能包括含有整个选项树的默认 IWebOpts。 接下来考虑 ISSL 中存储的选项。 这些选项用于 SSL 协商，以确定密码组、协议、版本及其它， 还可以内部传递给 IX509Chain 实例，作为证书链验证的选项。 也就是说，您可以在此添加或传递 IX509Chain 选项。 特别是传递根证书集和主机名。

如果要返回创建的 IX509Chain 实例，以便检查或存储链中的证书，则您可以传递非 NULL 的 pCerts 参数，或者设置将接口置于链中的 web 选项。

协商具有不同的行为，具体取决于连接的状态、WEBOPT_SSL_TRUST_MODE 以及调用协商还是再协商。 三种连接状态为不安全、中止协商和安全状态。

以上 WEBOPT_SSL_TRUST_MODE 说明适用于不安全状态下的协商或再协商调用。 通常，如果出现信任错误，ISSL 将关闭到服务器的连接，并且不允许覆盖 ISSL。 这是未设置 WEBOPT_SSL_TRUST_MODE，或将其设置为 SSL_TRUST_MODE_FAIL 的情况。 如果将 WEBOPT_SSL_TRUST_MODE 设置为 SSL_TRUST_MODE_CHECK，则不会关闭该连接。

然后可再次调用 ISSL_Negotiate()，并很可能通过某种 X509TrustOverride 继续 SSL 会话（尽管发生了信任错误）。 如果模式设置为 SSL_TRUST_MODE_IGNORE，
则将忽略所有信任错误，从而极大地威胁到连接安全。 如果模式设为 SSL_TRUST_MODE_ALWAYS，则完成信任检查后，将始终触发该回调。 这允许您检查并拒绝信任链，即使链接引擎可以成功地对其进行验证。

一种可能的操作模式是，在第一个协商调用中使用 SSL_TRUST_MODE_CHECK，
检查信任错误后在第二个 ISSL_Negotiate() 调用中使用 SSL_TRUST_MODE_IGNORE。 如果将第一个协商调用设置为 SSL_TRUST_IGNORE，大部分 SSL 安全将会失效！！ 以下是可能的信任模式。

SSL_TRUST_MODE_FAIL 默认模式，出现信任错误时失败

SSL_TRUST_MODE_CHECK 出现信任错误时中止，可以检查并忽略信任错误

SSL_TRUST_MODE_IGNORE 忽略所有信任错误

SSL_TRUST_MODE_ALWAYS 始终中止，因此可以始终检查信任

处于中止状态时，任何协商或再协商调用将使协商继续，直至成功或失败。

安全状态下的调用则显得怪异、反常和有趣。 如果在安全状态下调用再协商，将会发生新的协商。

执行 ISSL_Renegotiate() 的原因令人费解，但 SSL 和此处将支持此操作。 （标准中规定最好刷新密钥材料，但您必须传输大约 2^78 字节的内容才会出现问题）。 如果在安全状态下调用协商，将根据各种选项（特别是密码组和根证书）所包含的安全级别来评估连接的安全级别。 如果匹配，则返回“成功”，否则，将返回“失败”。 无论是成功还是失败，连接本身不会受到干扰。 其目的是评估保持激活的会话以便再次使用。 尽管并不常用，但这种方法还是被应用于 HTTPS 的内部实现。

如果将 WEBOPT_SSL_SESSIONDB 选项设为实例化的 IRecordStore 接口，则此选项将用于存储和取回会话的恢复数据。 协商成功后，将通过添加调用在此接口提供
的数据库或缓存中存储一个记录。 尝试协商前，将对此数据库或缓存的执行“查找”调用以查找之前已存储的任何会话。 这些会话的存储时间可能为应用程序的使用期或更长。 如果它们的存储时间较长，则应引起重视，因为这些记录包含会话的重要机密。

协商结束后，请检查 pinfo 结构以获得详细信息，最重要的是获得安全 ISocket 的实例。 此 ISocket 的用法与其它所有 ISocket 相同。 ISSL 未处理的所有 IOCTL 将继续传递到 ISocket（已传递至 ISSL_SetSocket）。 调用 ISOCKET_Release 相当于调用 ISSL_Release。

下面概括了影响协商的 WebOpts。 请注意，所有影响 IX509CHAIN_Verify 的 WebOpts 也将影响协商。

WEBOPT_SSL_SEC_INFO | 获取协商的 SSLInfo 结果的备选方法。 它对 IWeb 和 HTTPS 均适用。
WEBOPT_SSL_TRUST_MODE | 指定出现信任错误时的常规行为。
WEBOPT_SSL_ALLOWED_CIPHER_ SUITES | 提供可用于协商的密码组有序列表的多个选项。 这些选项必须为 SSL_CSUITE_* 之一。
WEBOPT_SSL_ALLOWED_VERSIONS | 提供可用于协商的协议版本有序列表的多个选项。 这些选项必须为 SSL_VERSION_* 之一。
WEBOPT_SSL_WANT_X509_CHAIN | 设置选项以获取根据以下 web 选项内部创建的 X509Chain。 此选项允许您检查、显示或保存证书链。 如果设置使用内存来存储链，则所有证书将一直保存到销毁接口或删除该选项。
WEBOPT_SSL_X509_CHAIN | 将返回内部使用的 IX509Chain 对象引用的选项。 它是单个值，无需设置。
WEBOPT_SSL_SESSIONDB | 会话恢复的实例化接口。 此接口必须是 IRecordStore 接口（如 IRamCache）。 如果没有设置此接口，或设置为 NULL，则会话恢复不存在。

另请参阅：

SSLInfo

ISSL_NegotiateV()

ISSL_Renegotiate()

ISSL_RenegotiateV()

返回函数列表。

ISSL_NegotiateV()

说明：

此函数将用于进行 SSL 握手。 如果握手尚未开始，它将启动握手。 如果握手正在进行，它将继续此握手。 如果已建立握手，它将报告与请求相关的握手状态。

原型：

void ISSL_NegotiateV
(ISSL *pISSL,
SSLInfo *pinfo,
IX509Chain **pCerts,
AEECallback *pcb,
WebOpts *pOpts
);

参数：

pISSL | 接口指针
pinfo | 放置响应结构的位置
IX509Chain **pCerts | ISSL 返回证书链的位置
pcb | SSL 成功、失败或需要帮助时回调的位置
popt | 执行协商所依据的选项集

返回值：

无

备注：

注意：请参阅 ISSL_Negotiate() 的备注：部分中的论述。

另请参阅：

SSLInfo

ISSL_Negotiate()

ISSL_Renegotiate()

ISSL_RenegotiateV()

返回函数列表。

ISSL_QueryInterface()

说明：

此函数继承于 IQI_QueryInterface()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

返回函数列表

ISSL_Release()

说明：

此函数用于释放 ISSL 引用。

原型：

void ISSL_Release(ISSL *pISSL);

参数：

pISSL
接口指针

返回值：

无

备注：

如果引用计数达到零，则释放所有保存的内存，并取消所有回调。 回调应明确取消，而不是依靠 ISSL_Release。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISSL_AddRef()

返回函数列表

ISSL_RemoveOpt()

说明：

此函数继承于 IWEBOPTS_GetOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISSL_AddOpt()

返回函数列表

ISSL_Renegotiate()

说明：

除了在已建立连接的情况下需要重新协商之外，再协商与 ISSL_Negotiate() 完全一样。注意：本版本不支持ISSL_Renegotiate()。

原型：

void ISSL_Renegotiate(ISSL *pISSL, SSLInfo *pinfo, IX509Chain **pCerts, AEECallback *pcb, ...)

参数：

pISSL | 接口指针
pinfo | 放置响应结构的位置
IX509Chain **pCerts | ISSL 返回证书链的位置
pcb | SSL 成功、失败或需要帮助时回调的位置
... | 执行协商所依据的选项集

返回值：

无

备注：

注意：请参阅 ISSL_Negotiate() 的备注：部分中的论述。

另请参阅：

ISSL_Negotiate()

ISSL_NegotiateV()

ISSL_RenegotiateV()

返回函数列表

ISSL_RenegotiateV()

说明：

除了在已建立连接的情况下需要重新协商之外，再协商与 ISSL_Negotiate() 完全一样。注意：本版本不支持ISSL_RenegotiateV()。

原型：

void ISSL_RenegotiateV
(
ISSL *pISSL,
SSLInfo *pinfo,
IX509Chain **pCerts,
AEECallback *pcb,
WebOpts *pOpts
)

参数：

pISSL | 接口指针
pinfo | 放置响应结构的位置
IX509Chain **pCerts | ISSL 返回证书链的位置。
pcb | SSL 成功、失败或需要帮助时回调的位置。
pOpts 或 ... | 执行协商所依据的选项集。

返回值：

无

备注：

注意：请参阅 ISSL_Negotiate() 的备注：部分中的论述。

另请参阅：

ISSL_Negotiate()

ISSL_NegotiateV()

ISSL_Renegotiate()

返回函数列表

ISSL_SetSocket()

说明：

要提供打开并连接至 SSL 服务器的套接字，必须调用此函数。

原型：

void ISSL_SetSocket(ISSL *pISSL, ISocket *pISocket)

参数：

pISSL | 接口指针。
pISocket | 指向打开的套接字的指针。

返回值：

无

备注：

传递的 ISocket 必须已打开并连接至准备开始 SSL 协商的服务器。 请注意，所传递的 ISocket 是具有 vtable 的对象。 它不一定是标准的 Brew ISocket，还可以是实现 ISocket 的其它对象。 通过此机制，ISSL 可用于数据流对象之外的其它对象。

另请参阅：

无

返回函数列表


IStatic 接口

IStatic 接口允许您创建由只读文本消息和显示在控件矩形顶部的标题组成的静态文本控件。
与 ITextCtl 接口创建的文本控件不同，设备用户不能输入或修改静态文本控件中的文本。 在控件矩形中文本消息将分行显示，每一行的字符数均为整数（即一个单词不会分两行显示）。 如果文本消息太长不能完全显示在设备屏幕中，静态文本控件将自动滚屏显示。 到达消息末尾时，则从头开始继续滚动。 除了用文本消息作为控件内容，您还可以选用 IImage 接口创建的动画位图。 如果选择该选项，位图将显示在静态文本控件矩形的中央。IStatic 接口提供了许多属性来自定义静态文本控件的外观和行为。 这些属性没有初始设置，请使用 ISTATIC_SetProperties() 函数设置如下：

  • ST_ICONTEXT 指示使用动画位图而非文本消息。 设置该属性后，ISTATIC_SetText() 将得到指向 IImage 接口实例而非消息文本字符串的指针（参见本节后面部分）。
  • ST_TEXTALLOC 告知 ISTATIC_SetText() 不要为消息文本字符串分配存储空间（如果已经为代码中的消息字符串分配了存储空间，则可以设置该属性）。
  • ST_TITLEALLOC 告知 ISTATIC_SetText() 不要为控件标题字符串分配存储空间（如果已经为代码中的标题分配了存储空间，则可以设置该属性）。
  • ST_NOSCROLL 禁用长文本消息自动滚屏显示（在以后版本中，该属性允许设备用户使用“向上”和“向下”键手动滚动文本）。
  • ST_MIDDLETEXT 指定消息文本在控件矩形中垂直居中排列（默认情况下，
    文本从矩形顶部开始，紧接控件标题的下方）。
  • ST_UNDERLINE 为控件标题加下划线。
  • ST_CENTERTEXT 使每行消息文本居中排列（默认情况下，控件矩形中的行是左对齐的）。
  • ST_CENTERTITLE 可以使控件标题居中排列（默认情况下，标题是左对齐的）。
  • ST_ASCII，文本是否为单字节
  • ST_ENABLETAB，处于顶部或底部时是否生成 EVT_CTL_TAB。
  • ST_ENABLE_HLGHT，是否突出显示获得焦点的静态控件。

使用静态文本控件一般包括如下几个步骤（关于每个 IStatic 接口函数的参数列表和返回值的详细信息，请参阅后面各部分的函数说明和 IStatic 接口使用示例）：

使用静态文本控件

  1. 使用 ISHELL_CreateInstance() 创建 IStatic 接口实例。
  2. 使用 ISTATIC_SetRect() 设置控件矩形的尺寸。
  3. 通过读取 BREW 资源文件或代码中的文本字符串，获取控件标题文本和文本消息字符串。 如果使用位图来替代文本消息，请读取位图并使用 IIMAGE_SetParm() 函数设置其动画属性（帧数、动画速率和其它属性）。
  4. 调用 ISTATIC_SetText() 指定控件的标题字符串、消息字符串或位图，以及标题和文本使用的字体。 在调用 ISTATIC_SetText() 之前必须调用 ISTATIC_SetRect()（参见步骤 2），因为后者要使用控件矩形的信息来确定如何显示控件。
  5. 调用 ISTATIC_Redraw() 在屏幕上显示控件的内容。
  6. 不需要该控件时，请调用 ISTATIC_Release()。 该函数将释放控件消息文本和标题占用的内存，但“不会”释放动画位图。 如果在步骤 3 中创建了 IImage 接口实例，则须将其另行释放。

要包含的头文件列表

需要以下头文件：

AEEShell.h

函数列表

该接口的函数包括：

ISTATIC_AddRef()

ISTATIC_GetProperties()

ISTATIC_GetRect()

ISTATIC_GoToLine()

ISTATIC_HandleEvent()

ISTATIC_IsActive()

ISTATIC_IsScrollable()

ISTATIC_Redraw()

ISTATIC_Release()

ISTATIC_Reset()

ISTATIC_SetActive()

ISTATIC_SetFont()

ISTATIC_SetProperties()

ISTATIC_SetRect()

ISTATIC_SetText()

ISTATIC_SetTextEx()

ISTATIC_SizeToFit()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ISTATIC_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ISTATIC_Release()

返回函数列表

ISTATIC_GetProperties()

说明：

此函数用于获取 IStatic 接口对象的属性。 属性可决定对象的实际外观和感觉。

原型：

uint32 ISTATIC_GetProperties(IStatic * pIStatic)

参数

:

pIStatic
指向 IStatic 接口对象的指针。

返回值：

如果文本居中，则返回 ST_CENTERTEXT。

如果标题居中，则返回 ST_CENTERTITLE。

如果设置了不滚动显示文本，则返回 ST_NOSCROLL。

如果在堆上分配文本- 对话框负责释放文本，则返回 ST_TEXTALLOC。

如果在堆上分配标题 -对话框负责释放标题，则返回 ST_TITLEALLOC。

如果在屏幕中央绘制文本，则返回 ST_MIDDLETEXT。

如果设置了为标题加下划线，则返回 ST_UNDERLINE。

如果文本为 llmage，则返回 ST_ICONTEXT。

如果文本为单字节，则返回 ST_ASCII。

如果在顶部或底部时生成 EVT_CTL_TAB，则返回 ST_ENABLETAB。

如果突出显示具有焦点的静态控件，则返回 ST_ENABLE_HLGHT。

备注：

无

另请参阅：

ISTATIC_SetProperties()

返回函数列表

ISTATIC_GetRect()

说明：

此函数用于获取 IStatic 接口对象的位置和大小。

原型：

void ISTATIC_GetRect(IStatic * pIStatic, const AEERect * prc)

参数

:

pIStatic | 指向 IStatic 接口对象的指针。
prc | 指向 IStatic 对象矩形（位置和大小）的指针。

返回值：

无

备注：

无

另请参阅：

ISTATIC_SetRect()

AEERect

返回函数列表

ISTATIC_GoToLine()

说明：

此函数允许调用者自动滚屏到指定行。 nLine 参数是基于 0 的索引值。

原型：

int ISTATIC_GoToLine(IStatic * pIStatic, int nLineIdx)

参数：

pIStatic | 指向 IStatic 对象的指针
nLineIdx | 滚动显示的索引。

返回值：

前一索引值。

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_HandleEvent()

说明：

此函数用于为激活的 IStatic 接口对象处理按键事件。

原型：

boolean ISTATIC_HandleEvent
(
IStatic * pIStatic,
AEEEvent eCode,
uint16 wParam,
uint32 dwParam
)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
eCode | 事件代码。
wParam | 16 位第一事件参数。
dwParam | 32 位第二事件参数。

返回值：

如果已处理事件，则返回 TRUE。

如果尚未处理事件，则返回 FALSE。

备注：

无

另请参阅：

AEE 事件

返回函数列表

ISTATIC_IsActive()

说明：

如果 ISTATIC 当前是活动的，此方法将返回 TRUE，如果不活动，则返回 FALSE。

原型：

boolean ISTATIC_IsActive(IStatic * pIStatic)

参数：

pIStatic
指向 IStatic 接口对象的指针。

返回值：

如果 ISTATIC 是活动的，则返回 TRUE。

如果 ISTATIC 不活动，则返回 FALSE。

备注：

无

另请参阅：

ISTATIC_SetActive()

返回函数列表

ISTATIC_IsScrollable()

说明：

此方法允许调用程序确定分配给静态控件的空间是否足够容纳其中的文本。

原型：

boolean ISTATIC_IsScrollable(IStatic * pIStatic);

参数：

pIStatic
指向 IStatic 对象的指针

返回值：

如果无法容纳文本，需滚动控件，则返回 TRUE。

如果可以容纳文本，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_Redraw()

说明：

此函数用于刷新屏幕上的 IStatic 接口对象。

原型：

boolean ISTATIC_Redraw(IStatic * pIStatic)

参数：

pIStatic
指向 IStatic 接口对象的指针。

返回值：

始终返回 TRUE。

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_Release()

说明：

此函数用于减少 IStatic 接口对象的引用计数。 引用计数为 0（零）时，将从内存中释放该对象且不再有效。

原型：

uint32 ISTATIC_Release(IStatic * pIStatic)

参数：

pIStatic
指向 IStatic 接口对象的指针。

返回值：

已减少的对象引用计数。

如果已释放对象，且不再有效，则返回 0（零）。

备注：

如果返回 0（零），则对象已释放且不再有效。

另请参阅：

ISTATIC_AddRef()

返回函数列表

ISTATIC_Reset()

说明：

此函数用于将 IStatic 对象的内容设置为 null。 标题将保留不变。

原型：

void ISTATIC_Reset(IStatic * pIStatic)

参数：

pIStatic
指向 IStatic 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_SetActive()

说明：

此方法用于将选中的 ISTATIC 设置为激活或不激活。

原型：

void ISTATIC_SetActive(IStatic * pIStatic, boolean bActive)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
bActive | TRUE 表示将该 ISTATIC 设置为活动。 FALSE 表示将它设置为不活动。

返回值：

无

备注：

ISTATIC 对象不能进行编辑，但是将其选中后，如果已打开 ST_ENABLE_HLGHT 属性，则会在其周围显示一个方框。 当有许多对象在屏幕上时，它将有助于告知用户当前选中的对象。

另请参阅：

ISTATIC_IsActive()

ISTATIC_SetProperties()

ST_ENABLE_HLGHT

返回函数列表

ISTATIC_SetFont()

说明：

此函数允许调用程序设置标题和文本字体。

原型：

void ISTATIC_SetFont
(
IStatic * pIStatic,
AEEFont fntText,
AEEFont fntTitle
)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
fntText | 文本使用的字体。
fntTitle | 标题使用的字体。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_SetProperties()

说明：

此函数用于设置 IStatic 接口对象的属性。 属性值可以决定对象的实际外观和感觉。

原型：

void ISTATIC_SetProperties(IStatic * pIStatic, uint32 nProperties)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
nProperties | 属性值。 |
 | ST_CENTERTEXT | 使文本居中排列。
 | ST_CENTERTITLE | 使标题居中排列。
 | ST_NOSCROLL | 不滚动显示文本。
 | ST_TEXTALLOC | 在堆上分配文本 -对话框负责释放文本。
 | ST_TITLEALLOC | 在堆上分配标题 -对话框负责释放标题。
 | ST_MIDDLETEXT | 在屏幕中央绘制文本。
 | ST_UNDERLINE | 为标题加下划线。
 | ST_ICONTEXT | 文本为 llmage。
 | ST_ASCII | 文本为单字节
 | ST_ENABLETAB | 处于顶部或底部时生成 EVT_CTL_TAB。
 | ST_ENABLE_HLGHT | 突出显示获得焦点的静态控件。

返回值：

无

备注：

在将来的版本中，属性 ST_NOSCROLL 可使您通过上下箭头键手动滚动长文本消息。 在当前版 BREW 中，此属性禁用了长消息自动滚动（用户无法完整地读取这些
消息）。

另请参阅：

ISTATIC_GetProperties()

返回函数列表

ISTATIC_SetRect()

说明：

此函数用于设置IStatic 接口对象的位置和大小。

原型：

void ISTATIC_SetRect(IStatic * pIStatic, const AEERect * prc)

参数：

pIStatic

指向 IStatic 接口对象的指针。
prc
指向 IStatic 接口对象矩形（位置和大小）的指针。

返回值：

无

备注：

无

另请参阅：

ISTATIC_GetRect()

AEERect

返回函数列表

ISTATIC_SetText()

说明：

此函数用于设置IStatic 接口对象的文本和标题。

原型：

boolean ISTATIC_SetText
(
IStatic * pIStatic,
AECHAR * pTitle,
AECHAR * pText,
AEEFont fntTitle,
AEEFont fntText
)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
pTitle | 指向标题字符串的指针。
pText | 指向文本字符串的指针。
fntTitle | 标题字体类型。
fntText | 文本字体类型。

返回值：

如果文本和标题设置正确，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

AEEFont

返回函数列表

ISTATIC_SetTextEx()

说明：

此方法用于设置 IStatic 对象的文本。 此函数允许调用程序：

  • 根据传递给 ISTATIC_SetProperties 函数的标记，来指定文本宽度为单字节或双字节。 除非已经设置了 ST_ASCII 属性，否则默认情况下将视为双字节文本。
  • 附加或替换现有文本
  • 从输入流读取文本。 这可以使调用程序避免缓冲文件或套接字文本。

请注意下列事项：

  • 标题文本“始终”假定为双字节。 ST_ASCII 仅影响文本，不影响标题。
  • 更改 ST_ASCII 属性将自动释放或重置控件中的文本。
  • 设置或清除 ST_ASCII 属性后，所有的文本操作都假定为单字节或双字节。
  • 传递 pbText 和 pStream 参数，添加或替换 pbText 中的现有文本，然后从流中读取文本。

原型：

boolean ISTATIC_SetTextEx
(
IStatic * pIStatic,
byte * pbText,
IAStream * pStream,
boolean bAppend
)

参数：

pIStatic | 指向 IStatic 接口对象的指针。
pbText | 指向文本的指针。
pStream | 指向文本流的指针。
bAppend | TRUE 表示附加文本，FALSE 表示重置文本。

返回值：

如果已设置或添加文本，则返回 TRUE。

如果没有设置或添加文本，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ISTATIC_SizeToFit()

说明：

此方法允许调用程序调整绑定矩形的大小，以便它可以容纳 IStatic 中的所有文本。

原型：

void ISTATIC_SizeToFit(IStatic * pIStatic, AEERect *prc);

参数：

pIStatic | 指向 IStatic 接口对象的指针
prc | 指向设置绑定矩形位置的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表


ITAPI 接口

ITAPI 接口是一个简单的设备通话层接口。 该函数提供以下服务：

  • 获取状态
  • 安排语音呼叫
  • 从 SMS 消息中提取 SMS 文本
  • 获取进入或正在呼叫的主叫号码

ITAPI 接口可通过 ISHELL_CreateInstance() 函数获得。

要包含的头文件列表

ITAPI 需要以下头文件

AEETAPI.h

函数列表

此接口的函数包括：

ITAPI_AddRef()

ITAPI_ExtractSMSText()

ITAPI_GetCallerID()

ITAPI_GetStatus()

ITAPI_IsDataSupported()

ITAPI_IsVoiceCall()

ITAPI_MakeVoiceCall()

ITAPI_OnCallStatus()

ITAPI_OnCallEnd()

ITAPI_Release()

ITAPI_SendSMS()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ITAPI_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITAPI_Release()

返回函数列表

ITAPI_ExtractSMSText()

说明：

此函数用于从原始 SMS 消息中提取格式化文本。 输入的参数格式是 AEESMSMsg。 返回的缓冲区在下次调用 ITAPI_ExtractSMSText() 或释放接口之前将一直有效。
当应用程序注册 NMASK_TAPI_SMS_TEXT 通知时，将获取 dwParam 指向的 AEENotify 的 pData 中的 AEESMSMsg。

使用此函数的典型方法是：

  1. 使用 MIF Editor（或使用 ISHELL_RegisterNotify()）注册 AEECLSID_TAPI 类的 NMASK_TAPI_SMS_TEXT 通知。
  2. 当入局 SMS 文本消息进入系统时，向应用程序发送 EVT_NOTIFY 事件，
    其中，dwParam 指向的 AEENotify 结构的 pData 将指向 AEESMSMsg 结构。
  3. 将此结构传至 ITAPI_ExtractSMSText()，以提取消息的格式化文本部分。

原型：

AEESMSTextMsg * ITAPI_ExtractSMSText
(
ITAPI * pITAPI,
const AEESMSMsg * pMsg
)

参数：

pITAPI | 指向 ITAPI 接口对象的指针。
pMsg | 指向输入 AEESMSMsg 的指针。

返回值：

如果失败，则返回 NULL。

备注：

设备模拟器不支持此函数。

另请参阅：

AEESMSMsg

AEESMSTextMsg

返回函数列表

ITAPI_GetCallerID()

说明：

此函数用于获取进入或外发语音呼叫的数字 ID。

原型：

boolean ITAPI_GetCallerID(ITAPI * pITAPI, AECHAR * pDest, int nSize)

参数：

pITAPI | 指向 ITAPI 接口对象的指针。
pDest | 目标指针。
nSize | 目标缓冲区大小（字节）。

返回值：

如果正在进行呼叫，并已填充缓冲区，则返回 TRUE。

如果没有呼叫或缓冲区无效，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITAPI_GetStatus()

说明：

此函数用于获取通话设备的当前状态，包括服务和呼叫状态。 应用程序也可以通过 ISHELL_RegisterNotify()函数注册接收因变化而产生的 TAPIStatus 更新信息。

原型：

int ITAPI_GetStatus(ITPAI * pITAPI, TAPIStatus * ps)

参数：

pITAPI | 指向 ITAPI 接口对象的指针。
ps | 指向要填充的状态信息的指针。

返回值：

如果状态信息有效，则返回 SUCCESS。

如果参数错误，则返回 EBADPARM。

备注：

无

另请参阅：

TAPIStatus

ISHELL_RegisterNotify()

返回函数列表

ITAPI_IsDataSupported()

说明：

此方法可用于确定手持设备是否支持数据服务。

原型：

boolean ITAPI_IsDataSupported(ITapi *pITAPI)

参数：

pITAPI
指向 ITAPI 对象的指针

返回值：

e:

如果手持设备支持数据服务，则返回 TRUE

如果手持设备不支持数据服务，则返回 FALSE

备注：

无

另请参阅：

无

返回函数列表

ITAPI_IsVoiceCall()

说明：

此方法可用于确定系统中的当前呼叫是否为语音呼叫。

原型：

boolean ITAPI_IsVoiceCall(ITapi *pITAPI)

参数：

pITAPI
指向 ITAPI 对象的指针

返回值：

如果当前呼叫为语音呼叫，则返回 TRUE

如果当前呼叫“不”是语音呼叫，则返回 FALSE

备注：

无

另请参阅：

ITAPI_MakeVoiceCall()

返回函数列表

ITAPI_MakeVoiceCall()

说明：

此方法用于安排语音呼叫。 拨叫的号码通过数字字符串指定。 如果输入的是空串或 NULL，则不安排呼叫。 只允许使用以下数字：0-9、#、*。其它数字均将忽略。
如果正在进行语音呼叫，则返回 EALREADY。 如果正在进行数据呼叫但是没有网络活动 (TCP)，则结束数据呼叫而安排语音呼叫。

该函数可以实现运营商确立的保密策略， 其中包括以对话框方式提供给用户的中间
提示。

通常，调用此函数时，将出现一个对话框，询问用户是否安排呼叫。 如果用户单击“是”，则安排该呼叫。

调用此函数时，应用程序的事件流程为：

  1. 向用户显示对话框。
  2. 清除对话框时，将事件 EVT_DIALOG_END 发送至应用程序。
  3. 此时，应用程序必须刷新屏幕。
  4. 如果用户同意安排呼叫，则将事件 EVT_APP_SUSPEND 发送至应用程序。
  5. 呼叫完成时，将事件 EVT_APP_RESUME 发送至应用程序。
  6. 应用程序必须刷新屏幕。

原型：

int ITAPI_MakeVoiceCall
(
ITAPI * pITAPI,
const char * pszNumber,
AEECLSID clsReturn
)

参数：

pITAPI | 指向 ITAPI 接口对象的指针
pszNumber | 指向外拨号码的指针
clsReturn | 调用完成时要运行的小程序的 Classid

返回值：

如果函数正在进行，则返回 SUCCESS。

如果号码无效，则返回 EBADPARM。

如果已有进行中的语音呼叫，则返回 EALREADY。

备注：

如果 clsReturn 为 0，则恢复当前应用程序。

另请参阅：

无

返回函数列表

ITAPI_OnCallEnd()

说明：

此方法与 ITAPI_OnCallStatus() 相同。

原型：

int ITAPI_OnCallEnd
(
ITAPI * pITAPI,
PFNNOTIFY pfn,
void * pUser,
uint32 dwDelay,
uint16 wFlags
)

参数：

请参阅 ITAPI_OnCallStatus()

返回值：

请参阅 ITAPI_OnCallStatus()

备注：

无

另请参阅：

请参阅 ITAPI_OnCallStatus()

返回函数列表

ITAPI_OnCallStatus()

说明：

此方法可用于注册回调函数，当呼叫状态发生变化时，BREW 将调用该回调函数。
它支持用于指定应用程序所关注呼叫状态类型的标记。

原型：

int ITAPI_OnCallStatus
(
ITAPI * pITAPI,
PFNNOTIFY pfn,
void * pUser,
uint32 dwDelay,
uint16 wFlags
)

参数：

pITAPI | 指向 ITAPI 对象的指针
pfn | 呼叫状态发生变化时调用的通知函数
pUser | 调用通知函数时传递给它的用户数据。
dwDelay | 呼叫状态变化后、通知应用程序前，BREW 等待的时间量（毫秒）。
wFlags | 支持的标记如下：
 | OCS_CANCEL | 取消以前注册的回调函数
 | OCS_UNIQUE_PFN | 通常，可以使用函数地址 (pfn) 和用户数据 (pUser) 来确定是否已定义 CB 函数。 因此，应用程序可以通过指定不同的用户数据多次注册同一 CB 函数。 如果设置此标记，则只可注册一次 CB 函数（忽略用户数据的差别）。
 | OCS_ONE_SHOT | 通知 BREW 只能为一个通知注册此 CB 函数。 一旦发生单个呼叫状态变化，则将调用此通知并从内部列表中将该 CB 函数删除， 而不再调用此 CB。
 | OCS_INCOMING | 注册进入呼叫的通知
 | OCS_ORIG | 注册发起呼叫的通知
 | OCS_CONVERSATION | 注册呼叫进入对话状态（例如双向状态） 的通知
 | OCS_IDLE | 注册呼叫结束的通知
 | OCS_OFFLINE | 注册电话超出覆盖范围的通知
 | OCS_ALL | 注册所有呼叫状态转换（进入、发起、对话和空闲）

返回值：

如果注册成功，则返回 SUCCESS

如果失败，则返回 ENOMEMORY

备注：

无

另请参阅：

无

返回函数列表

ITAPI_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITAPI_AddRef()

返回函数列表

ITAPI_SendSMS()

说明：

此方法用于从手持设备发送 SMS 消息。该函数可以用来向其它手持设备的特定 BREW 应用程序发送文本消息，或者向其它手持设备发送通用文本消息。 它将把消息发送到目标移动号码或电子邮件 ID。调用此函数后，它可能会在 BREW 应用程序中产生 SUSPEND/RESUME 序列。 手持设备发送 SMS 消息时将对它进行初始化。

控制序列流程如下：

  1. 应用程序调用 ITAPI_SendSMS(pITapi,pszDst,pszMsg,0,MyNotify,pMe)
  2. 手持设备开始发送 SMS 消息
  3. 应用程序接收 EVT_APP_SUSPEND
  4. 在发送消息的状态下调用 pfn 指定的通知函数
  5. 应用程序接收 EVT_APP_RESUME

如果应用程序希望显示通知信息，则建议在调用通知函数时存储状态，然后在收到 EVT_APP_RESUME 时显示该状态。

原型：

int ITAPI_SendSMS
(
ITAPI *pITapi,
const char * pszDst,
const char * pszMsg,
AEECLSID clsDst,
PFNSMSSTATUS pfn,
void *pUser
)

参数：

pITapi | 指向 ITAPI 接口对象的指针
pszDst | 发送消息的目标号码或电子邮件 ID。 如果将其设为 NULL，并且 clsDst 非零，则此函数将向本地手持设备上的应用程序 (clsDst) 发送 EVT_APP_MESSAGE 事件，而该事件的 dwParam 将包含 pszMsg。 在此情况下，该函数的返回值与 ISHELL_SendEvent() 的返回值相同。 由于是本地发送消息，因此不会调用通知函数。
pszMsg | 要发送至目标移动设备的文本消息。 如果设为 NULL，则函数将返回 EBADPARM
clsID | 如果非零，则它指定目标移动设备上接收该消息的 BREW 应用程序的类 ID
pfn | 通知 SMS 消息发送状态所调用的通知函数
pUser | 发送至通知函数的用户数据 示例： ITAPI_SendSMS (pITapi, "8581112222", "Hello World", 0, MyMOSMSNotify, pMe ); ITAPI_SendSMS ( pITapi, "foo@sample.com", "Hello World", 0, MyMOSMSNotify, pMe );

返回值：

如果成功，则返回 SUCCESS。 将消息发送至其它手持设备后，使用状态调用该通知函数。 传送至通知函数的状态可能为 SUCCESS 或 Failure。

如果电话正忙，无法发送该 SMS，则返回 EITEMBUSY。 通常，只允许存在一个未完成的 SMS 消息。 除非已发送该消息，否则不可以发送其它消息。

如果 pszMsg 为 NULL，或 pszDst 和 clsDst 均设为 NULL，则返回 EBADPARM。

如果此手持设备未启用 TAPI，则返回 EBADCLASS。

如果发送 SMS 时发生常规故障，则返回 EFAILED。

示例：

ITAPI_SendSMS(pITapi, "8581112222", "Hello World", 0, MyMOSMSNotify, pMe);

ITAPI_SendSMS(pITapi, "foo@sample.com", "Hello World",0,MyMOSMSNotify,pMe);

备注：

无

另请参阅：

无

返回函数列表


ITextCtl 接口

文本控件使设备用户能够使用设备上的按键输入文本字符串。 文本控件由可选的标题和矩形窗口组成，窗口中包含一行或多行显示给用户的输入文本。 文本控件将设备用户的按键操作转换成字符。 应用程序只需将按键事件传递给激活的文本控件，并在设备用户完成文本输入时从该控件获取文本。 转换过程取决于设备支持的文本输入模式，例如标准多次按键模式（设备用户从映射到每个按键的字符中选择）和 Tegic T9 预测文本输入模式}。 如果支持多种文本输入模式，应用程序可以使设备用户在文本控件激活时选择指定的模式。 文本控件允许您指定用于此目的的软键菜单。 在文本控件激活时，应用程序必须通过调用 ITEXTCTL_HandleEvent() 向它发送所有按键事件。

文本控件支持下列可用 ITEXTCTL_SetProperties() 设置的属性（属性名称是用于设置和测试属性值的位掩码常量名）：

  • TP_MULTILINE 允许在文本输入窗口显示多行文本（默认情况下只显示单行
    文本）。
  • TP_FRAME 绘制文本控件的外框。
  • TP_T9_MODE 指定 T9 为设备默认的文本输入模式（如果未设置，则默认为多次按键模式）。 BREW Emulator 不支持该模式。
  • TP_FIXSETRECT，如果设置该属性，则实际高度可以更确切地代表请求的高度。

除 IControl 接口的函数之外，文本控件还提供了若干函数。ITEXTCTL_SetTitle() 和 ITEXTCTL_SetText() 指定控件标题和文本输入窗口显示的文本字符串值（后一个函数能够为设备用户可编辑的窗口内容提供初始值）。ITEXTCTL_GetText() 获取控件文本字符串的当前值并将其复制到缓冲区。ITEXTCTL_GetTextPtr() 与之类似，不同的是，它返回文本控件中用来保存文本的字符串指针，而不复制该文本。ITEXTCTL_SetMaxSize() 决定可输入到文本控件中的最大字符数。ITEXTCTL_EnableCommand() 允许在设备用户按下“选择”键时向应用程序发送 EVT_COMMAND（目前不支持该函数）。

ITEXTCTL_SetSoftKeyMenu() 用于将软键菜单控件与文本控件关联。 它通常是您创建并在显示文本控件时出现在屏幕上的软键菜单。ITEXTCTL_SetSoftKeyMenu() 用于向软键菜单添加项目，允许设备用户更改文本输入模式（该项目的文本字符串指示当前选择的模式）。 收到该命令时，文本控件显示一个菜单，允许设备用户选择新的文本输入模式。 设备用户选择新模式后，文本控件重新激活，设备用户继续输入文本。 输入文本时，设备用户可以按“选择”键离开文本编辑模式并激活软键菜单。 软键菜单激活时，设备用户可以按“向上”键返回编辑模式，而不进行菜单选择。

在应用程序中使用文本控件

  1. 调用 ISHELL_CreateInstance() 创建文本控件实例。
  2. 调用 ITEXTCTL_SetRect() 指定包含文本控件的屏幕矩形。
  3. 指定屏幕矩形后，调用 ITEXTCTL_SetTitle() 或 ITEXTCTL_SetText() 指定控件的标题及控件的文本字符串初始值。
  4. 调用 ITEXTCTL_SetProperties() 设置文本控件属性。
  5. 调用 ITEXTCTL_SetSoftKeyMenu() 指定与该文本控件关联的软键菜单
    （如果有）。
  6. 调用 ITEXTCTL_SetActive() 激活文本控件并在屏幕上显示其内容。
  7. 文本控件激活时，调用 ITEXTCTL_HandleEvent() 向它传递用户生成的所有按键事件。
  8. 当设备用户完成文本输入时，调用 ITEXTCTL_GetText() 或 ITEXTCTL_GetTextPtr() 获取设备用户输入的文本（如果使用软键菜单，设备用户可以使用菜单中的“完成”项指示文本输入结束，如果没有软键菜单则可以按“选择”键或其它键）。
  9. 如果不再需要文本控件，调用 ITEXTCTL_Release() 将其释放。

要包含的头文件列表

ITextCtl 需要以下头文件

AEEText.h

函数列表

此接口的函数包括：

ITEXTCTL_AddRef()

ITEXTCTL_EnableCommand()

ITEXTCTL_EnumModeInit()

ITEXTCTL_EnumNextMode()

ITEXTCTL_GetCursorPos()

ITEXTCTL_GetInputMode()

ITEXTCTL_GetProperties()

ITEXTCTL_GetRect()

ITEXTCTL_GetText()

ITEXTCTL_GetTextPtr()

ITEXTCTL_HandleEvent()

ITEXTCTL_IsActive()

ITEXTCTL_Redraw()

ITEXTCTL_Release()

ITEXTCTL_Reset()

ITEXTCTL_SetActive()

ITEXTCTL_SetCursorPos()

ITEXTCTL_SetInputMode()

ITEXTCTL_SetMaxSize()

ITEXTCTL_SetProperties()

ITEXTCTL_SetRect()

ITEXTCTL_SetSoftKeyMenu()

ITEXTCTL_SetText()

ITEXTCTL_SetTitle()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ITEXTCTL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITEXTCTL_Release()

返回函数列表

ITEXTCTL_EnableCommand()

说明：

该函数用于在收到按下“选择”键产生的事件时，将文本控件对象指定的命令发往外壳对象。

原型：

void ITEXTCTL_EnableCommand
(
ITextCtl * pITextCtl,
boolean bEnable,
uint16 nCmdId
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针
bEnable | 启用/禁用标记的布尔值
nCmdId | 命令 ID

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_EnumModeInit()

说明：

此函数用于初始化测试控件的模式枚举机制。 任何时候要枚举文本控件，必须首先调用此函数。

原型：

void ITEXTCTL_EnumModeInit(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_EnumNextMode()

说明：

此函数用于枚举文本控件模式。

原型：

AEETextInputMode ITEXTCTL_EnumNextMode
(
ITextCtl * pITextCtl,
AEETextInputModeInfo * pmInfo
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针
pmInfo | 接收文本模式信息的可选指针。 如果您不想接收此信息，请使用 NULL 值作为第二参数调用此函数。

返回值：

指示下一个输入模式的 AEETextInputMode 类型枚举。

如果完成枚举，则返回 AEE_TM_NONE。

备注：

无

另请参阅：

AEETextInputMode

返回函数列表

ITEXTCTL_GetCursorPos()

说明：

此函数用于获取文本控件对象中的光标位置。

原型：

int32 ITEXTCTL_GetCursorPos(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针

返回值：

文本控件中光标的绝对位置

备注：

无

另请参阅：

ITEXTCTL_SetCursorPos()

返回函数列表

ITEXTCTL_GetInputMode()

说明：

此函数允许调用程序获取所选文本输入模式及其关联的字符串。

原型：

AEETextInputMode ITEXTCTL_GetInputMode
(
ITextCtl *pITextCtl,
AEETextInputModeInfo * pmInfo
)

参数：

pITextCtl | [in] | 指向 ITextCtl 接口对象的指针
pmInfo | [in/out] | 输入： 指向要填充的 AEETextInputModeInfo 信息结构的指针，或者为 NULL，无需填充结构并返回当前模式。 输出： 如果给定有效指针，则使用当前模式及其关联的字符串填充此指针。

返回值：

指示输入模式设置的 AEETextInputModeInfo 类型枚举。

备注：

如果给定 AEETextInputModeInfo 指针的 tmMode 字段，则它将匹配此函数的返回值。 如果调用程序仅检查 AEETextInputModeInfo 而不需要与其关联的字符串，则无需 pmInfo 字段。

另请参阅：

AEETextInputModeInfo

返回函数列表

ITEXTCTL_GetProperties()

说明：

此函数用于返回文本控件特定的属性或标记。

原型：

uint32 ITEXTCTL_GetProperties(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。

返回值：

文本控件的 32 位属性。

文本控件对象可返回以下属性：

TP_MULTILINE，如果设置该属性,则文本控件对象为多行控件。

TP_FRAME，如果设置该属性，则文本控件对象将具有外框。

TP_T9_MODE，如果设置该属性，则文本控件对象将使用 T9 模式。

TP_FIXSETRECT，如果设置该属性，则实际高度可以更确切地代表请求的高度。

备注：

无

另请参阅：

ITEXTCTL_SetProperties()

返回函数列表

ITEXTCTL_GetRect()

说明：

此函数用于为给定的 AEERect 指针填充当前文本（不是标题）绑定矩形大小的坐标。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

注意：

如果已设置 TP_FIXSETRECT 属性，则此函数将为 AEERect 填充控件的实际绑定矩形，而不一定是传递到 ITEXTCTL_SetRect() 中的矩形。

如果“未”设置 TP_FIXSETRECT 属性，则此函数将返回传入 ITEXTCTL_SetRect() 的矩形。

原型：

void ITEXTCTL_GetRect(ITextCtl * pITextCtl, AEERect * prc)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
prc | 要填入文本控件对象坐标的矩形。

返回值：

无

备注：

无

另请参阅：

AEERect

ITEXTCTL_SetRect()

返回函数列表

ITEXTCTL_GetText()

说明：

此函数用于读取给定缓冲区中与 ITextCtl 接口对象关联的文本，该文本大小由 nMaxChars 限制。

原型：

boolean ITEXTCTL_GetText
(
ITextCtl * pITextCtl,
AECHAR * pBuffer,
unsigned int nMaxChars
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
pBuffer | 文本占位符。
nMaxChars | 要读取的最大字符数。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

ITEXTCTL_GetTextPtr()

返回函数列表

ITEXTCTL_GetTextPtr()

说明：

此函数用于返回由 ITextCtl 对象保存的文本的指针。 该函数与 GetText 的区别是，
后者将内容复制到目标缓冲区，前者只返回 ITextCtl 对象中的文本的指针。

原型：

AECHAR * ITEXTCTL_GetTextPtr(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。

返回值：

指向文本控件对象的文本缓冲区的指针

备注：

无

另请参阅：

ITEXTCTL_GetText()

返回函数列表

ITEXTCTL_HandleEvent()

说明：

此函数用于处理文本控件对象收到的事件。 如果文本控件对象处于非编辑模式，则它只处理已有标题、已有文本及向上、向下按键事件； 如果在文本编辑模式下，则处理各种事件，如向上和向下按键、按键保持、已有标题、已有文本以及来自软键菜单的命令事件。

原型：

boolean ITEXTCTL_HandleEvent
(
ITextCtl * pITextCtl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
evt | 事件代码。
wp | 16 位事件数据。
dwp | 32 位事件数据。

返回值：

如果文本控件已处理该事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_IsActive()

说明：

此函数用于返回文本控件对象的激活状态。

原型：

boolean ITEXTCTL_IsActive(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。

返回值：

如果文本控件处于激活状态，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_Redraw()

说明：

此函数用于指示文本控件对象刷新其内容。ITextCtl 接口对象并非在文本控件底层数据每次更改时都进行刷新，它允许一次进行若干数据更新，从而使屏幕闪烁降至最低。 例如在调用 ITEXTCTL_Redraw() 函数之前，即使对文本控件对象的内容进行了若干更改，也看不到实际的效果。

原型：

boolean ITEXTCTL_Redraw(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。

返回值：

如果已刷新文本控件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITEXTCTL_AddRef()

返回函数列表

ITEXTCTL_Reset()

说明：

此函数用于指示文本控件清除（释放或删除）其内容，并立即离开激活/焦点模式。

原型：

void ITEXTCTL_Reset(ITextCtl * pITextCtl)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

ITEXTCTL_SetActive()

返回函数列表

ITEXTCTL_SetActive()

说明：

此函数用于激活文本控件对象。 只有激活的文本控件对象才能处理发送给它的事件，而未激活的文本控件对象将忽略这些事件。 未激活的文本控件对象也不绘制其边框。

原型：

void ITEXTCTL_SetActive(ITextCtl * pITextCtl, boolean bActive)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针。
bActive
布尔标记，指定：
  • TRUE：激活文本控件对象。
  • FALSE：停用文本控件对象。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_SetCursorPos()

说明：

此函数用于设置文本控件对象中的光标位置。 您可以使用以下 nOffset 定义将文本置于开头或结尾。

原型：

void ITEXTCTL_SetCursorPos(ITextCtl * pITextCtl, int32 nOffset)

参数：

pITextCtl
指向 ITextCtl 接口对象的指针
nOffset
文本对象的位置
  • TC_CURSOREND 表示将光标放在文本的结尾。
  • TC_CURSORSTART 表示将光标放在文本的开头。

返回值：

无

备注：

如果 nOffset 小于 0，则将光标放在文本的开头。

如果 nOffset 大于文本的长度，则将光标放在文本的末尾

另请参阅：

ITEXTCTL_GetCursorPos()

返回函数列表

ITEXTCTL_SetInputMode()

说明：

此函数允许调用程序设置所选文本输入模式。

原型：

AEETextInputMode ITEXTCTL_SetInputMode
(
ITextCtl * pITextCtl,
AEETextInputMode wMode
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
wMode | 文本输入模式。

返回值：

指示输入模式设置的 AEETextInputMode 类型的枚举。

备注：

无

另请参阅：

AEETextInputMode

返回函数列表

ITEXTCTL_SetMaxSize()

说明：

此函数用于设置文本控件对象支持的最大文本大小。 如果要设置的大小大于已有的设置，将释放与原有大小相关的内存，并按新的大小分配内存。

原型：

void ITEXTCTL_SetMaxSize (ITextCtl * pITextCtl, uint16 nMaxSize)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
nMaxSize | 以 AECHAR 字符表示的最大文本大小（不包括 NULL），若为 0（零）则不更改。

返回值：

无

备注：

此函数在不同设备上的实现可能不同。 某些设备可能允许输入超过此函数最大设置的文本。

另请参阅：

无

返回函数列表

ITEXTCTL_SetProperties()

说明：

此函数用于设置文本控件特定的属性或标记。

原型：

void ITEXTCTL_SetProperties(ITextCtl * pITextCtl, uint32 dwProps)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
dwProps | 32 位标记或属性组。

下列属性用于文本控件对象：

TP_MULTILINE，如果设置该属性,则文本控件对象为多行控件。

TP_FRAME，如果设置该属性，则文本控件对象将具有外框。

TP_T9_MODE，如果设置该属性，则文本控件对象将使用 T9 模式。

TP_FIXSETRECT，如果设置该属性，则实际高度可以更确切地代表请求的高度。

返回值：

无

备注：

无

副作用：

此函数将停用文本控件。

另请参阅：

ITEXTCTL_GetProperties()

返回函数列表

ITEXTCTL_SetRect()

说明：

此函数为 AEERect 数据结构填入当前绑定矩形的坐标，以确定文本（不是标题）
的大小。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

注意：

如果已设置 TP_FIXSETRECT 属性，此函数将为 AEERect 数据结构填入控件的实际绑定矩形，此矩形可能不是使用 ITEXTCTL_SetRect() 设置的矩形。

如果“未”设置 TP_FIXSETRECT 属性，此函数将返回 AEERect 数据结构，其中包含使用 ITEXTCTL_SetRect() 设置的矩形坐标。

原型：

void ITEXTCTL_SetRect(ITextCtl * pITextCtl, const AEERect * prc)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
prc | 文本控件对象的绑定矩形。

返回值：

无

备注：

默认情况下，文本控件对象的控件矩形从设备屏幕的左上角开始，将设备屏幕的宽度和高度分别作为其宽度和高度。

另请参阅：

AEERect

ITEXTCTL_GetRect()

返回函数列表

ITEXTCTL_SetSoftKeyMenu()

说明：

此函数以指定的菜单控件对象替换文本控件对象现有的软键菜单。

原型：

void ITEXTCTL_SetSoftKeyMenu(ITextCtl * pITextCtl, IMenuCtl * pm)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
pm | 软键菜单的新菜单控件对象。

返回值：

无

备注：

无

副作用：

如果文本管理器保留了输入模式字符串，则会增加 IMenuCtl 的引用计数，并向菜单添加一个新的菜单项。

另请参阅：

无

返回函数列表

ITEXTCTL_SetText()

说明：

此函数用于将给定的字符串指定为文本控件对象的文本。

原型：

boolean ITEXTCTL_SetText
(
ITextCtl * pITextCtl,
const AECHAR * psz,
int cch
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
psz | 要设置的文本字符串。
cch | 指定为文本控件对象文本的字符串中 AECHAR 字符的数目。 如果 cch 为负值或大于 psz 字符串的长度，则将使用字符串的长度。

返回值

无

备注：

无

另请参阅：

无

返回函数列表

ITEXTCTL_SetTitle()

说明：

此函数用于设置文本控件对象的标题。 如果 pText 不为 NULL，函数会将 pText 指定的字符串设置为文本控件对象的标题。 如果 pText 为 NULL，函数将从资源文件读取与给定的资源标识符相对应的标题字符串，并将其设置为文本控件对象的标题。

原型：

boolean ITEXTCTL_SetTitle
(
ITextCtl * pITextCtl,
const char * pszResFile,
uint16 wResID,
AECHAR * pText
)

参数：

pITextCtl | 指向 ITextCtl 接口对象的指针。
pszResFile | 包含资源字符串的文件。
wResID | 资源标识符。
pText | 以 NULL 结尾的标题字符串。

返回值：

如果成功，则返回 TRUE。

否则，返回 FALSE。

备注：

无

副作用：

如果 pText 为 NULL，且 pszResFile 和 WResID 有效，此函数将把 pText 赋值为文本控件对象的标题字符串。

另请参阅：

无

返回函数列表


ITimeCtl 接口

时间控件允许设备用户以多种格式输入时间值， 并向设备用户显示时间值。 在输入时间值时，设备用户可以按“向左”和“向右”键选择要修改的时间字段（即时、分或秒），
按“向上”和“向下”键增减编辑字段的值。 如果设备用户按下“选择”键并已启用命令发送（参阅本节后面的内容）， 则将向创建时间控件的应用程序或对话框发送 EVT_COMMAND
事件，通知应用程序设备用户已经完成时间值输入。 您还可以指定在时间控件中显示的时间值。 该功能可以不断更新该控件以反映时间值的变化。 例如，要实现秒表功能，时间控件并不通过设置计时器或访问当前时刻亲自度量时间，而必须在代码中使用类似 GETTIMEMS() 等函数来获取必要的时间值。

当 ITimeCtl 中的时间值发生更改时，此控件将向当前应用程序发送 EVT_CTL_CHANGING 事件。 该事件的 dwParam 指向 CtlValChange 结构。

以下是三类时间控件，它们均以不同的格式显示时间（创建时间控件的实例时，可指定 ClassID 来选择需要的类型）：

  • 时钟控件（ClassID 为 AEECLSID_CLOCKCTL）显示时、分数字和 AM/PM 指示器。 此类控件可用于指定闹钟开始的时间。
  • 倒数计时控件（ClassID 为 AEECLSID_COUNTDOWNCTL）显示时、分和秒数。 这种显示格式对倒数计时器很有用，可允许设备用户设置计时器持续时间，然后显示计时器到期前的剩余时间。
  • 秒表控件（ClassID 为 AEECLSID_STOPWATCHCTL）显示时、分、秒和百分秒数字， 可用于实现秒表功能。

编辑时间控件中最左和最右字段时，如果设备用户按下“向左”和“向右”键，时间控件将发送控件切换事件 (EVT_CTL_TAB)。 使用控件切换可在多控件屏幕中的控件间移动
（如果时间控件是对话框的一部分，对话框将截取控件切换事件并相应地改变控件焦点）。

时间控件支持若干可使用 ITIMECTL_SetProperties() 设置的属性（属性名称是用于测试和设置属性的位掩码常量名称）：

  • TP_AUTOREDRAW 可使时间控件在每次激活时都进行刷新。
  • TP_NO_SECONDS 使倒数计时控件不显示和编辑秒数字。
  • TP_NO_MSECONDS 在秒表控件中取消百分秒显示。
  • TP_NOEDIT_AMPM 使设备用户不能编辑时钟控件的 AM/PM 字段。
  • TP_LEFT_JUSTIFY 使要绘制的文本左对齐（默认为居中）

除了 IControl 接口的函数之外，时间控件还实现了若干其它函数。ITIMECTL_SetTime() 用于设置保存在时间控件中的时间值（毫秒），并以时间控件的格式显示其值。ITIMECTL_SetTimeEx() 是该函数的扩展版本，只更新显示的时间值，并不更新内部保存的值。ITIMECTL_GetTime() 用于获取保存在时间控件中的当前时间（毫秒）。ITIMECTL_GetTimeString() 将时间值（毫秒）作为输入，并将其转换成文本字符串，其中包含相应的小时、分钟数，并可选择包括秒、百分秒数和 AM/PM 指示器。 时间字符串的数字部分由冒号分隔。

ITIMECTL_EnableCommand() 用于启用或禁用在设备用户按下“选择”键时，向应用程序发送 EVT_COMMAND 事件（默认情况下，禁用命令发送）。ITIMECTL_SetIncrement() 用于设置在用户按“向上”或“向下”箭头键编辑文本控件的分钟字段时增加或减少的分钟数（默认值为一分钟）。ITIMECTL_SetEditField() 用于指定设备用户编辑的时间控件字段，
可能值为时、分或秒字段（如果为时钟控件指定了秒字段，则可选择 AM/PM 字段，假设其可编辑）。 设备用户使用“向左”和“向右”箭头键选择要编辑的字段，
而 ITIMECTL_SetEditField() 可用于选择要编辑的初始字段。

创建和使用时间控件

  1. 调用 ISHELL_CreateInstance()，用 ClassID 从三类时间控件中指定需要的类型，创建时间控件实例并获取其接口指针。
  2. 调用 ITIMECTL_SetTime() 指定时间控件的初始时间值（如果指定了一个时间控件）。
  3. 调用 ITIMECTL_SetRect() 定义要在其中绘制时间控件的屏幕矩形。
  4. 调用 ITIMECTL_SetProperties() 设置任何时间控件属性。 调用 ITIMECTL_SetIncrement() 或 ITIMECTL_SetEditField() 更改默认的分钟增量或初始编辑字段。
  5. 在指定了时间控件的内容和属性以后，调用 ITIMECTL_SetActive() 在屏幕上绘制该控件并（如果控件支持设备用户编辑）使之能够接收设备用户选择时间值的按键事件。 时间控件激活时，应用程序的 IAPPLET_HandleEvent() 函数必须调用 ITIMECTL_HandleEvent() 向时间控件传递所有已处理的按键事件进行处理。
  6. 要向设备用户显示变化的时间值，请调用 ITIMECTL_SetTime() 或 ITIMECTL_SetTimeEx() 在每次时间值变化时更新显示。
  7. 要访问设备用户输入的时间值，请在设备用户输入值之后（设备用户可以按
    “选择”键或退出包含时间控件的屏幕来指示完成输入）调用 ITIMECTL_GetTime()。 调用 ITIMECTL_GetTimeString() 可将毫秒数转换成可印刷的形式。
  8. 如果不再需要时间控件，则调用 ITIMECTL_Release() 将其释放。

要包含的头文件列表

需要以下头文件：

AEETime.h

函数列表

此接口的函数包括：

ITIMECTL_AddRef()

ITIMECTL_EnableCommand()

ITIMECTL_GetFont()

ITIMECTL_GetProperties()

ITIMECTL_GetRect()

ITIMECTL_GetTime()

ITIMECTL_GetTimeString()

ITIMECTL_HandleEvent()

ITIMECTL_IsActive()

ITIMECTL_Redraw()

ITIMECTL_Release()

ITIMECTL_Reset()

ITIMECTL_SetActive()

ITIMECTL_SetEditField()

ITIMECTL_SetFont()

ITIMECTL_SetIncrement()

ITIMECTL_SetProperties()

ITIMECTL_SetRect()

ITIMECTL_SetTime()

ITIMECTL_SetTimeEx()

ITIMECTL_SizeToFit()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ITIMECTL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITIMECTL_Release()

返回函数列表

ITIMECTL_EnableCommand()

说明：

该函数用于启用在接收到按下中心键生成的事件后，向发送 AEE 外壳发送时间控件对象指定的命令。

原型：

void ITIMECTL_EnableCommand
(
ITimeCtl * pITimeCtl,
boolean bEnable,
uint16 nCmdId
)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
bEnable | 用作启用/禁用标记的布尔值。
nCmdId | 命令 ID。

返回值：

无

备注：

此函数不支持 ITimeCtl 接口的秒表视图。

另请参阅：

无

返回函数列表

ITIMECTL_GetFont()

说明：

此方法允许调用程序获取时间数字和字母的字体。

原型：

boolean ITimeCTL_GetFont
(
ITimeCtl * pITimeCtl,
AEEFont *pfntNum,
AEEFont *pfntLetter
)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针
pfntNum | 指向设置数字字体位置的指针
pfntLetter | 指向设置字母 (AM/PM) 字体位置的指针

返回值：

如果成功，则返回 TRUE

如果失败，则返回 FALSE

备注：

无

另请参阅：

AEEFont

ITIMECTL_SetFont()

返回函数列表

ITIMECTL_GetProperties()

说明：

此函数用于返回时间控件特定的属性或标记。

原型：

uint32 ITIMECTL_GetProperties(ITimeCtl * pITimeCtl)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。

返回值：

时间控件的 32 位属性。

时间控件对象可返回下列属性：

TP_AUTOREDRAW，如果设置该属性，则控件将在 ITIMECTL_SetActive() 时
刷新。

TP_NO_SECONDS，如果设置该属性，则控件不在“倒数计时”控件中显示
秒数。

TP_NO_MSECONDS，如果设置该属性，则控件不在“秒表”控件中显示毫秒。

TP_NOEDIT_AMPM，如果设置该属性，则控件不允许编辑 AM/PM。

TP_LEFT_JUSTIFY，如果设置该属性，则左对齐绘制文本（默认为居中）。

备注：

无

另请参阅：

ITIMECTL_SetProperties()

返回函数列表

ITIMECTL_GetRect()

说明：

此函数用于将时间控件对象绑定矩形的坐标填入给定的 AEERect 指针。 在创建控件后确定其最佳/默认的大小和位置时，此函数特别有用。

原型：

void ITIMECTL_GetRect(ITimeCtl * pITimeCtl, AEERect * prc)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
prc | 要填入时间控件坐标的矩形。

返回值：

无

备注：

无

另请参阅：

AEERect

ITIMECTL_SetRect()

返回函数列表

ITIMECTL_GetTime()

说明：

此函数用于从时间控件对象获得时间值。 时间值以毫秒表示。

原型：

int32 ITIMECTL_GetTime(ITimeCtl * pITimeCtl)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。

返回值：

该对象自 00:00:00 开始经过的时间（毫秒）。

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_GetTimeString()

说明：

此函数用于将毫秒表示的时间转换成指定格式的字符串。

原型：

void ITIMECTL_GetTimeString
(
ITimeCtl * pITimeCtl,
uint32 dwSecs,
AECHAR * pDest,
unsigned int nSize,
uint16 wFlags
)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。
dwSecs
以毫秒表示的要转换成字符串的时间。
pDest
已转换为字符串格式的时间。
nSize
Pdest 的大小（字节）。
wFlags
指定用于字符串转换的时间格式的位映像，支持以下类型：
  • GTS_MSECS： 使用百分秒，并显示两位百分秒。
  • GTS_SECS： 使用秒。
  • GTS_AMPM： 使用 AM 或 PM。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_HandleEvent()

说明：

此函数用于处理时间控件对象收到的事件。 时间控件对象仅在激活时处理收到的事件。 它处理上下左右键的按键事件。 如果已启用命令发送，则时间控件对象将在收到按下中心键生成的事件后，将 ITIMECTL_EnableCommand() 函数指定的命令作为命令事件发送到 AEE 外壳。

原型：

boolean ITIMECTL_HandleEvent
(
ITimeCtl * pITimeCtl,
AEEEvent evt,
uint16 wp,
uint32 dwp
)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
evt | 事件代码。
wp | 16 位事件数据。
dwp | 32 位事件数据。

返回值：

如果时间控件已处理该事件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_IsActive()

说明：

此函数用于返回 ITimeCtl 接口对象的激活或非激活状态。

原型：

boolean ITIMECTL_IsActive(ITimeCtl * pITimeCtl)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。

返回值：

如果该时间控件处于激活状态，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_Redraw()

说明：

此函数用于指示时间控件对象刷新其内容。 时间控件对象并非在每次更改底层数据时都进行刷新， 它允许一次进行若干数据更新，从而使屏幕闪烁降至最低。 例如，
在调用“刷新”函数之前，即使更改若干时间控件对象的内容，也看不到实际的
效果。

原型：

boolean ITIMECTL_Redraw(ITimeCtl * pITimeCtl)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。

返回值：

如果已刷新时间控件，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITIMECTL_AddRef()

返回函数列表

ITIMECTL_Reset()

说明：

此函数用于指示时间控件清除（释放或删除）其内容，并立即脱离激活或焦点模式。

原型：

void ITIMECTL_Reset(ITimeCtl * pITimeCtl)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。

返回值：

无

备注：

无

另请参阅：

ITIMECTL_SetActive()

返回函数列表

ITIMECTL_SetActive()

说明：

此函数用于激活时间控件对象。 只有激活的时间控件对象才能处理发送给它的事件； 未激活的时间控件对象将忽略这些事件。

原型：

void ITIMECTL_SetActive(ITimeCtl * pITimeCtl, boolean bActive)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。
bActive
布尔标记，指示：
  • TRUE： 激活时间控件对象。
  • FALSE： 停用时间控件对象。

返回值：

无

备注：

始终停用秒表类。 时钟和倒数计时类可以使用 ITIMECTL_SetActive()。

另请参阅：

无

返回函数列表

ITIMECTL_SetEditField()

说明：

此函数用于设置指定的字段进行编辑。

原型：

void ITIMECTL_SetEditField(ITimeCtl * pITimeCtl, ITField field)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针
field
要设置进行编辑的字段， 可以是：
  • ITF_HOUR
  • ITF_MIN
  • ITF_SEC

返回值：

无

备注：

此函数不支持 ITimeCtl 接口的秒表视图。 时钟视图不包含秒数，因此请勿为时钟视图设置 ITF_SEC。

另请参阅：

ITField

返回函数列表

ITIMECTL_SetFont()

说明：

此方法使调用程序可以设置标题和文本字体。

原型：

void ITimeCtl_SetFont
(
ITimeCtl * pITimeCtl,
AEEFont fntNum,
AEEFont fntLetter
)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针
fntNum | 时间数字将要使用的字体。 如果此参数设为 NULL，则假设使用默认字体 AEE_FONT_LARGE
fntLetter | 时间的非数字部分 (AM/PM) 将要使用的字体。 如果此参数设为 NULL，则假设使用默认字体 AEE_FONT_BOLD

返回值：

无

备注：

无

另请参阅：

AEEFont

ITIMECTL_GetFont()

返回函数列表

ITIMECTL_SetIncrement()

说明：

此函数用于设置新的时间增量值（分钟）。 默认值为 1。

原型：

void ITIMECTL_SetIncrement(ITimeCtl * pITimeCtl, uint16 wMins)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
wMins | 新的时间增量值（分钟）。

返回值：

无

备注：

只能设置分钟字段的增量， 无法设置其它所有字段。 此函数不支持 ITimeCtl 接口的秒表视图。

另请参阅：

无

返回函数列表

ITIMECTL_SetProperties()

说明：

此函数用于设置时间控件特定的属性。

原型：

void ITIMECTL_SetProperties(ITimeCtl * pITimeCtl, uint32 dwProps)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。
dwProps
32 位标记或属性组。 时间控件对象可使用下列属性：
  • TP_AUTOREDRAW，如果设置该属性，则在 ITIMECTL_SetActive() 时刷新。
  • TP_NO_SECONDS，如果设置该属性，则“倒数计时”控件中不显示秒。
  • TP_NO_MSECONDS，如果设置该属性，则“秒表”控件中不显示毫秒。
  • TP_NOEDIT_AMPM，如果设置该属性，则不允许编辑 AM/PM。
  • TP_LEFT_JUSTIFY，如果设置该属性，则左对齐绘制文本
    • （默认为居中）。

返回值：

无

备注：

无

另请参阅：

ITIMECTL_GetProperties()

返回函数列表

ITIMECTL_SetRect()

说明：

此函数用于将 prc 指定的坐标设置为时间控件对象的控件矩形。

原型：

void ITIMECTL_SetRect(ITimeCtl * pITimeCtl, const AEERect * prc)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
prc | 时间控件的绑定矩形。

返回值：

无

备注：

默认情况下，整个设备屏幕将设置为时间控件对象的控件矩形。

另请参阅：

AEERect

ITIMECTL_GetRect()

返回函数列表

ITIMECTL_SetTime()

说明：

此函数用于设置给定的时间并在设备屏幕上刷新时间字符串。 它跟以 FALSE 作为第三个参数调用 ITIMECTL_SetTimeEx 的作用相同。

原型：

boolean ITIMECTL_SetTime(ITimeCtl * pITimeCtl, int32 tod)

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针。
tod | 从 00:00:00 开始的终止时间（毫秒），忽略负值。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

ITIMECTL_SetTimeEx()

说明：

此函数用于设置给定的时间，并刷新设备屏幕上的时间字符串。

原型：

boolean ITIMECTL_SetTimeEx
(
ITimeCtl * pITimeCtl,
int32 tod,
boolean bIncUpdate
)

参数：

pITimeCtl
指向 ITimeCtl 接口对象的指针。
tod
从 00:00:00 开始的终止时间（毫秒），忽略负值。
bIncUpdate
布尔标记：
  • TRUE 表示将时间字符串保存在时间控件对象的缓冲区中，并在屏幕上绘制。
  • FALSE 表示只在屏幕上绘制，而不保存时间字符串。
无论是 TRUE 还是 FALSE，都将保存时间整数。

返回值：

如果输入时间有效，返回TRUE。

如果无效，返回FALSE。

备注：

bIncUpdate 参数只影响 ITimeCtl 接口对象的时间字符串。 始终保存时间整数。

另请参阅：

无

返回函数列表

ITIMECTL_SizeToFit()

说明：

此方法允许调用程序将矩形调整为时间文本大小。

原型：

void ITimeCTL_SizeToFit(ITimeCtl * pITimeCtl, AEERect *prc);

参数：

pITimeCtl | 指向 ITimeCtl 接口对象的指针
prc | 指向设置绑定矩形位置的指针

返回值：

无

备注：

无

另请参阅：

AEERect

返回函数列表


ITransform 接口

ITransform 同 IBitmap 一样提供访问位图的函数。 此接口可提供通过变换执行位块传输操作的函数。 它支持两种变换，简单变换（使用 ITRANSFORM_TransformBltSimple()）和任意仿射变换（使用 ITRANSFORM_TransformBltComplex()）。

要包含的头文件列表

需要以下头文件：

AEETransform.h

函数列表

此接口的函数包括：

ITRANSFORM_AddRef()

ITRANSFORM_QueryInterface()

ITRANSFORM_Release()

ITRANSFORM_TransformBltComplex()

ITRANSFORM_TransformBltSimple()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

ITRANSFORM_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITRANSFORM_Release()

返回函数列表

ITRANSFORM_QueryInterface()

说明：

此函数检索指向符合指定类 ID 定义的接口的指针。它可用于查询扩展功能，如未来版本或专有功能。 查询成功时，将返回一个增加的接口实例。 调用程序负责在将来调用 Release()。 返回指针不是接口指针的情况除外。 在这种情况下，内存与正被查询的对象具有相同的使用期，所返回的指针将不用于释放对象。

原型：

int ITRANSFORM_QueryInterface(ITransform *pITransform, AEECLSID id, void **p);

参数：

pITransform | [in] | 指向 ITransform 接口的指针。
id | [in] | 标识正在尝试查询的实体（接口或数据）的全局唯一 id。
p | [out] | 指向要检索的数据或接口的指针。 如果传递回来的值为 NULL， 则表示要查询的接口或数据不存在。

返回值：

如果成功，则返回 SUCCESS。

否则，将返回错误代码。

备注：

如果失败，*pITransform 将设置为 NULL。但最好在调用 QueryInterface() 之前将 *pITransform 明确设置为 NULL。

另请参阅：

无

返回函数列表

ITRANSFORM_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

ITRANSFORM_AddRef()

返回函数列表

ITRANSFORM_TransformBltComplex()

说明：

原型：

int ITRANSFORM_TransformBltComplex
(
ITransform *pITransform,
int xDst,
int yDst,
IBitmap *pSrc,
int xSrc,
int ySrc,
unsigned dxSrc,
unsigned dySrc,
const AEETransformMatrix *pMatrixTransform,
uint8 unComposite
)

参数：

pITransform | 指向 ITransform 接口对象的指针。
xDst, yDst | 目标中将要绘制源左上角的坐标。 此处假定没有应用任何变换。 该位置由源区域中心指定，而源区域中心将绘制于目标中的 (xDst + dxSrc / 2, yDst + dySrc / 2) 处。
pSrc | 源位图。
xSrc, ySrc | 要位块传输至目标的源位图左上角。
dxSrc, dySrc | 要位块传输的源位图区域的宽度和高度。
pMatrixTransform | 指向指定所用变换的 AEEMatrixTransform 结构的指针。
unComposite | 请参阅 ITransform 属性。

返回值：

如果成功，则返回 SUCCESS。

如果不支持位块传输，则返回 EUNSUPPORTED。

备注：

无

另请参阅：

AEEMatrixTransform

ITransform 属性

返回函数列表

ITRANSFORM_TransformBltSimple()

说明：

此函数可以运用一系列预定义的简单变换，将一个位图位块传输至其它位图。

原型：

int ITRANSFORM_TransformBltSimple
(
ITransform *pITransform,
int xDst,
int yDst,
IBitmap *pSrc,
int xSrc,
int ySrc,
unsigned dxSrc,
unsigned dySrc,
uint16 unTransform,
uint8 unComposite)

参数：

pITransform | 指向 ITransform 接口的指针。
xDst, yDst | 目标中将要绘制源左上角的坐标。 此处假定没有应用任何变换。 该位置由源区域中心指定，而源区域中心将绘制于 目标中的 (xDst + dxSrc / 2, yDst + dySrc / 2) 处。
pSrc | 源位图。
xSrc, ySrc | 要位块传输至目标的源位图左上角。
dxSrc, dySrc | 要位块传输的源位图区域的宽度和高度。
unTransform | 指定要执行的变换的标记集。 请参阅 ITransform 属性。
unComposite | 请参阅 ITransform 属性。

返回值：

如果成功，则返回 SUCCESS。

如果不支持位块传输，则返回 EUNSUPPORTED。

备注：

无

另请参阅：

ITransform 属性

返回函数列表


IUnzipAStream 接口

IUnzipAStream 接口用于扩展 IAStream 接口，允许将压缩的 IAStream 解压缩并以流方式读取。 IUnzipAStream 的实例可以通过 ISHELL_CreateInstance() 函数（使用 classID AEECLSID_UNZIPSTREAM）创建。 此接口只能解压缩使用压缩存储空间算法（为 gzip 所采用）压缩的数据。

要包含的头文件列表

需要以下头文件：

AEEUnzipStream.h

函数列表

此接口的函数包括：

IUNZIPASTREAM_AddRef()

IUNZIPASTREAM_Cancel()

IUNZIPASTREAM_Read()

IUNZIPASTREAM_Readable()

IUNZIPASTREAM_Release()

IUNZIPASTREAM_SetStream()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IUNZIPASTREAM_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IUNZIPASTREAM_Release()

返回函数列表

IUNZIPASTREAM_Cancel()

说明：

此函数用于取消 IUnzipAStream 接口调度的回调。

原型：

void IUNZIPASTREAM_Cancel
(
IUnzipAStream * pIUnzipAStream,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIUnzipAStream | 指向 IUnzipAStream 接口对象的指针。
pfn | 指向要取消回调的回调函数的指针。
pUser | 指向用户指定数据的指针，该数据作为参数传递给回调函数， 用于标识必须取消的回调。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IUNZIPASTREAM_Read()

IUNZIPASTREAM_Readable()

返回函数列表

IUNZIPASTREAM_Read()

说明：

此函数用于尝试从流中读取数据，并返回读取的字节数。 如果没有数据可以读取，
则返回 AEE_STREAM_WOULDBLOCK 值。

原型：

int32 IUNZIPASTREAM_Read
(
IUnzipAStream * pIUnzipAStream,
void * pBuffer,
uint32 dwCount
)

参数：

pIUnzipAStream | 指向 IUnzipAStream 接口对象的指针。
pBuffer | 指向读入数据的缓冲区的指针。
dwCount | 读取的字节数。

返回值：

如果数据可读取，则返回已读取的字节数。

如果已经读取所有可读取数据，则返回 0（零）。

如果当前没有可以读取的数据，则返回 AEE_STREAM_WOULDBLOCK。

备注：

无

另请参阅：

IUNZIPASTREAM_Readable()

IUNZIPASTREAM_Cancel()

返回函数列表

IUNZIPASTREAM_Readable()

说明：

此函数用于注册一个回调来检验是否有可读取的数据。 如果 IUNZIPASTREAM_Read() 返回 AEE_STREAM_WOULDBLOCK，则调用该函数。

原型：

void IUNZIPASTREAM_Readable
(
IUnzipAStream * pIUnzipAStream,
PFNNOTIFY pfn,
void * pUser
)

参数：

pIUnzipAStream | 指向 IUnzipAStream 接口对象的指针。
pfn | 指向回调函数的指针。
pUser | 指向用户指定数据的指针，该数据作为参数传递给回调函数。

返回值：

无

备注：

无

另请参阅：

PFNNOTIFY

IUNZIPASTREAM_Read()

IUNZIPASTREAM_Cancel()

返回函数列表

IUNZIPASTREAM_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IUNZIPASTREAM_AddRef()

返回函数列表

IUNZIPASTREAM_SetStream()

说明：

这种方法允许用户将输入压缩流设置为 IUnzipAStream 的源。 用户可以创建压缩文件（如 .gzip 文件）、内存缓冲区或套接字的 IUnzipAStream，并将其作为输入传递至 IUnzipAStream 接口对象。 随后，IUNZIPASTREAM_Read() 将解压输入流并读取请求的字节数。如果有更多可以读取的解压数据，IUNZIPASTREAM_Readable() 将设置回调。

原型：

void IUNZIPASTREAM_SetStream
(
IUnzipAStream * pIUnzipAStream,
IUnzipAStream * pInIUnzipAStream
)

参数：

pIUnzipAStream | 指向 IUnzipAStream 接口的指针
pInIUnzipAStream | 指向压缩内存流的指针。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表


IViewer 接口

IViewer 接口与 IImage 接口完全相同， 二者均包含同样的函数列表。

IImage 函数的说明同样适用于 IViewer 函数（请参阅 函数列表 ）。

除了将 IIMAGE 替换为 IVIEWER 以外，函数原型几乎一样。

所使用的参数和 IImage 相同， 仅将参数 pIImage 替换为 pIViewer（IViewer 接口对象）。

返回值和 IImage 接口的返回值相同。

适用于 IImage 函数的备注同样适用于 IViewer 函数。

适用于 IImage 函数的副作用也适用于 IViewer 函数。

IImage 函数之间的另请参阅关系也适用于 IViewer 函数之间。

要包含的头文件列表

需要以下头文件：

AEEImage.h

函数列表

此接口的函数包括：

IVIEWER_AddRef() | 请参阅 IIMAGE_AddRef()。
IVIEWER_Draw() | 请参阅 IIMAGE_Draw()。
IVIEWER_DrawFrame() | 请参阅 IIMAGE_DrawFrame()。
IVIEWER_DrawOffscreen() | 请参阅 IIMAGE_DrawOffscreen()。
IVIEWER_GetInfo() | 请参阅 IIMAGE_GetInfo()。
IVIEWER_HandleEvent() | 请参阅 IIMAGE_HandleEvent()。
IVIEWER_Notify() | 请参阅 IIMAGE_Notify()。
IVIEWER_Release() | 请参阅 IIMAGE_Release()。
IVIEWER_SetAnimationRate() | 请参阅 IIMAGE_SetAnimationRate()。
IVIEWER_SetDrawSize() | 请参阅 IIMAGE_SetDrawSize()。
IVIEWER_SetFrameCount() | 请参阅 IIMAGE_SetFrameCount()。
IVIEWER_SetOffset() | 请参阅 IIMAGE_SetOffset()。
IVIEWER_SetParm() | 请参阅 IIMAGE_SetParm()。
IVIEWER_SetStream() | 请参阅 IIMAGE_SetStream()。
IVIEWER_Start() | 请参阅 IIMAGE_Start()。
IVIEWER_Stop() | 请参阅 IIMAGE_Stop()。

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。


IVocoder 接口

IVocoder 接口使用默认的声音路径，以捕获和播放声码器帧。 IVocoder 使用的设备也可以用来执行语音呼叫，因此使用 IVocoder 的应用程序必须注意并集成 TAPI 通知，以便在启动语音呼叫时适时停止使用声码器。 为应用程序配置 IVocoder 前，运营商应注意全面测试此
集成。

IVocoder 要求以近实时的方式进行有效操作。 例如，CDMA 声码器帧的持续时间为 20ms。
如果在 IVocoder 流化时，该应用程序或其它应用程序大量使用 CPU，会对语音质量产生不良影响，但不会导致手持设备出现问题。

正确的语音服务选项呼叫操作取决于正确的 ITAPI 处理应用程序实现。 应用程序必须能够在呼叫状态变为 PS_INCOMING 或 PS_ORIG（参阅 PhoneState）时释放声码器（配置为 VOC_NONE）。

IVocoder 接口注册 ITAPI_OnCallStatus()，并在呼叫进入对话状态时调用 voc_register_packet_clients 删除回调，在呼叫退出对话状态时建立回调。

IVocoder 接口提供了新的回调函数 VocoderAvailable，并在返回声码器时调用此函数。
这样应用程序可以在发生更改时执行操作。

要包含的头文件列表

需要以下头文件：

AEEVocoder.h

函数列表

此接口的函数包括：

IVOCODER_AddRef()

IVOCODER_GetFrameLength()

IVOCODER_GetInDepth()

IVOCODER_GetOutDepth()

IVOCODER_PlayTone()

IVOCODER_Release()

IVOCODER_VocConfigure()

IVOCODER_VocInRead()

IVOCODER_VocInReset()

IVOCODER_VocInStart()

IVOCODER_VocInStop()

IVOCODER_VocOutReset()

IVOCODER_VocOutStart()

IVOCODER_VocOutStop()

IVOCODER_VocOutWrite()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IVOCODER_AddRef()

说明：

此函数用于增加 IVocoder 对象的引用计数

原型：

uint32 IVOCODER_AddRef(IVocoder* pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针。

返回值：

已增加的使用计数器。

备注：

请注意，ISHELL_CreateInstance 将把引用计数初始化为 1。

另请参阅：

IVOCODER_Release()

返回函数列表

IVOCODER_GetFrameLength()

说明：

此函数用于提供给定速率的指定声码器帧的大小

原型：

int16 OEMVocoder_GetFrameLength
(
IVocoder * pVoc,
VocoderType vocoder,
DataRateType rate,
uint16 * pLength
);

参数：

pVoc | 指向 IVocoder 对象的指针。
vocoder | 帧的声码器类型。
rate | 帧的数据速率。
pLength | 指向保存帧大小的存储空间的指针。

返回值：

给定声码器/速率的帧大小（字节）；如果提供的参数错误，则返回-1。

备注：

使用此方法无需配置声码器。

另请参阅：

无

返回函数列表

IVOCODER_GetInDepth()

说明：

此函数用于获取已排队的编码帧数量。

原型：

int16 IVOCODER_GetInDepth(IVocoder* pVoc, uint16* pDepth);

参数：

pVoc | 指向 IVocoder 对象的指针。
pDepth | 指向保存排队帧计数的存储空间的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果输入参数 pDepth 错误，则返回 EBADPARM。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

无

另请参阅：

无

返回函数列表

IVOCODER_GetOutDepth()

说明：

此函数用于获取排队等待播放的帧数量。

原型：

int16 IVOCODER_GetOutDepth(IVocoder* pVoc, uint16* pDepth);

参数：

pVoc | 指向 IVocoder 接口对象的指针。
pDepth | 指向保存排队帧计数的存储空间的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果输入参数错误，则返回 EBADPARM。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

无

另请参阅：

无

返回函数列表

IVOCODER_PlayTone()

说明：

此函数用于通过声码器播放音调。

原型：

int16 OEMVocoder_PlayTone
(
IVocoder * pVoc,
uint16 tone1,
uint16 tone2,
int16 volume,
uint16 duration
);

参数：

pVoc | 指向 IVocoder 对象的指针。
tone1 | 第一个音调的频率。
tone2 | 第二个音调的频率。
volume | 音调的音量。
duration | 音调的持续时间。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

如果当前正在播放或获取 IVOCODER，则返回 AEE_VOC_EACTIVE。

备注：

只有当声码器已配置且未使用时，该函数才能播放音调。

另请参阅：

无

返回函数列表。

IVOCODER_Release()

说明：

此函数用于减少 IVocoder 对象的引用计数器。

原型：

int16 IVOCODER_Releate(IVocoder* pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针。

返回值：

如果操作成功，则返回 SUCCESS。

备注：

无

副作用：

使用计数为零时将释放声码器对象。

另请参阅：

IVOCODER_AddRef()

返回函数列表

IVOCODER_VocConfigure()

说明：

此函数用于配置声码器对象以使用特定的声码器。

原型：

int16 IVOCODER_VocConfigure
(
IVocoder* pVoc,
IVocoderConfigType config,
IVocoderInfoType* pInfo
);

参数：

pVoc | 指向 IVocoder 接口对象的指针。
config | 声码器对象的配置参数。
pInfo | 有关选定声码器的配置信息。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果水印值为零，则返回 EBADPARM。 水印值必须为正。

如果无法为声码器数据缓冲区分配内存，则返回 ENOMEMORY。

如果指定的声码器不可用，则返回 AEE_VOC_ENOT_AVAIL。

如果声码器不支持指定的最小或最大速率，则返回 AEE_VOC_ERATE_OUT_OF_RANGE。

如果 tx 减小值不正确，则返回 AEE_VOC_EBAD_TX_REDUCTION。

备注：

指定声码器类型为 VOC_NONE 将关闭所用的声码器设备。

副作用：

为声码器设备加电。

另请参阅：

IVocoderConfigType

返回函数列表

IVOCODER_VocInRead()

说明：

此函数用于获取队列中最旧的编码语音帧。

原型：

int16 IVOCODER_VocInRead
(
IVocoder* pVoc,
DataRateType* pRate,
uint16* pLength,
byte* pData
);

参数：

pVoc | 指向 IVocoder 接口对象的指针。
pRate | 指向接受帧数据速率的存储空间的指针。
pLength | 指向接受帧大小（字节）的存储空间的指针。
pData | 指向接受编码帧字节的存储空间的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

如果队列中没有编码帧，则返回 AEE_VOC_EBUFFER_EMPTY。

备注：

缓冲区大小必须足以支持声码器的最大帧速率，而不仅仅是当前速率限制所用的最
大值。

另请参阅：

haveDataCB

返回函数列表

IVOCODER_VocInReset()

说明：

此函数用于停止并清除编码声码器帧的队列

原型：

int16 IVOCODER_VocInReset(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

此操作是 InStop 功能的扩展集。

副作用：

停止接受和排队声码器中的编码帧，并释放已排队的帧。

另请参阅：

IVOCODER_VocInStop()

返回函数列表

IVOCODER_VocInStart()

说明：

开始编码语音帧。

原型：

int16 IVOCODER_VocInStart(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

帧可用时将调用“具有数据”回调。

副作用：

开始接受和排队声码器中的编码帧。

另请参阅：

haveDataCB

返回函数列表

IVOCODER_VocInStop()

说明：

停止编码语音帧。

原型：

int16 IVOCODER_VocInStop(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

不清除编码帧队列。

副作用：

停止接受和排队声码器中的编码帧。

另请参阅：

haveDataCB

返回函数列表

IVOCODER_VocOutReset()

说明：

此函数用于清除可解码帧的队列。

原型：

int16 IVOCODER_VocOutReset(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

如果声码器先前在播放，则它将等待帧，直至重置。

另请参阅：

needDataCB

返回函数列表

IVOCODER_VocOutStart()

说明：

此函数用于启动排队帧的解码及播放。

原型：

int16 IVOCODER_VocOutStart(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针

返回值：

如果操作成功，则返回 SUCCESS

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED

备注：

在队列中的待解码帧数未达到水印值之前，声码器不会启动。 这可能需要在队列中
附加足够的 ERASURE 帧，以满足水印值并启动播放。

另请参阅：

IVOCODER_VocOutWrite()

needDataCB

返回函数列表

IVOCODER_VocOutStop()

说明：

此函数用于停止排队帧的解码及播放。

原型：

int16 IVOCODER_VocOutStop(IVocoder * pVoc);

参数：

pVoc
指向 IVocoder 接口对象的指针

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

备注：

无

另请参阅：

无

返回函数列表

IVOCODER_VocOutWrite()

说明：

此函数用于为声码器提供新的数据帧

原型：

int16 IVOCODER_VocOutWrite
(
IVocoder* pVoc,
DataRateType rate,
uint16 length,
const byte* pData
);

参数：

pVoc | 指向 IVocoder 接口对象的指针。
rate | 帧的数据速率。
length | 帧大小（字节）。
pData | 指向帧数据字节的指针。

返回值：

如果操作成功，则返回 SUCCESS。

如果 IVOCODER 指针为 NULL，则返回 EBADCLASS。

如果帧的长度不适合指定速率，则返回 EBADPARM。

如果其它应用程序正使用 IVOCODER，则返回 AEE_VOC_EIN_USE。

如果未配置 IVOCODER，则返回 AEE_VOC_ENOT_CONFIGED。

如果输出队列不能接受更多的帧，则返回 AEE_VOC_EBUFFER_FULL。

如果已排列播放帧而未启动播放操作，则返回 AEE_VOC_ENOT_STARTED。

备注：

无

另请参阅：

needDataCB

返回函数列表


IWeb 接口

IWeb 接口是进行和完成 Web 处理的环境， 也是处理 BREW Web 支持的 API。 IWeb 接口指针在应用程序启动时创建、初始化，并使用到应用程序关闭。 IWeb 的一个有用的入口点是 IWEB_GetResponse()，它接受 URL 和 AEECallback，并取消异步的 Web 处理。 IWeb 可以监督代理、持续连接和其它的 Web 相关行为。 （请参阅 IWebOpts 接口）。

要包含的头文件列表

需要以下头文件：

AEEWeb.h

函数列表

此接口的函数包括：

IWEB_AddOpt()

IWEB_AddRef()

IWEB_GetOpt()

IWEB_GetResponse()

IWEB_GetResponseV()

IWEB_QueryInterface()

IWEB_Release()

IWEB_RemoveOpt()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IWEB_AddOpt()

说明：

此函数用于将一系列 Web 选项添加至当前的 Web 选项集。

原型：

int IWEB_AddOpt(IWeb * pIWeb, WebOpt * apwoz)

参数：

pIWeb | 指向 IWeb 接口对象的指针。
apwoz | WebOpt 结构数组，由 nId 设置为 WEBOPT_END 的 WebOpt 终止。

返回值：

如果成功添加选项，则返回 SUCCESS。

如果未分配足够的内存，则返回 ENOMEMORY。

备注：

无

另请参阅：

WebOpt

IWEB_GetOpt()

返回函数列表

IWEB_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEB_Release()

返回函数列表

IWEB_GetOpt()

说明：

此函数用于在 IWebOpts 接口对象的 WebOpts 列表中查找匹配 nOptId 的 WebOpt。 在多值 WebOpt 或覆盖的情况下，可能存在多个匹配。 这时，nIndex 将指定在匹配 nOptId 的 WebOpts 列表 中查找的距离。 pwo 参数中将填入匹配的 WebOpt 内容。 nIndex 参数的起始值为零。

原型：

int IWEB_GetOpt(IWeb * pIWeb, int32 nOptId, int32 nIndex, WebOpt * pwo)

参数：

pIWeb | 指向 IWeb 接口对象的指针。
nOptId | 要在选项列表中查找的选项 ID，如果有，WEBOPT_ANY 将返回 nIndexth 选项。
nIndex | 最近添加至具有相同 ID 的多个 Web 的 IWEB_AddOpt() 选项索引。
pwo | 保存找到的 WebOpt 的位置。

返回值：

如果成功检索到选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

WebOpt

IWEB_AddOpt()

返回函数列表

IWEB_GetResponse()

说明：

此函数通过确定接收 web 响应所需的资源和位置，开始 web 处理。

原型：

void IWEB_GetResponse
(
IWeb * pIWeb,
IWebResp * * ppiwresp,
AEECallback * pcb,
const char * cpszUrl,
...
)

参数：

pIWeb | 指向 IWeb 接口对象的指针。
ppiwresp | 指向接收资源的 IWebResp 接口对象的指针。 该对象必须在回调的使用期内有效。 完成后用户应将其释放。
pcb | 应答就绪时发送通知的回调信息。
cpszUrl | 请求文档的 URL。
... | WebOpt id/值对的变量列表，以 WEBOPT_END 结束。

返回值：

无

备注：

由于原型实际是通过函数指针调用的宏，因此必须像这样调用：

IWEB_GetResponse(pWeb, (pWeb, &pWResp, pcb, "http://www.qualcomm.com",
WEBOPT_SOMETHING, someval,
WEBOPT_SOMETHING2, someval2,
WEBOPT_END));

注意：变量参数的内括号是该调用的一部分。 将变量参数列表中提供给 _GetResponse() 的选项按顺序添加至 IWebOpt 对象，然后将该对象传递至协议处理程序。 这些选项将覆盖 IWeb 对象中已设置的任何选项。

例如：

通过 _AddOpt() 将 WEBOPT_CONNTIMEOUT 设置为 5000 的 IWeb 对象在 5 秒后将连接超时或进行故障转移，除非在 _GetResponse() 的参数中指定 WEBOPT_CONNTIMEOUT 才能够覆盖此行为。

传递给 _GetResponse() 的一个重要的 WEBOPT 是 WEBOPT_FLAGS，它影响底层协议引擎的行为。 以下是最新定义的 WEBREQUEST_* 标记， 调用 _GetResponse() 时可以使用这些标记。 “或”在逻辑上将它们用作一个 WebOpt：

WEBREQUEST_REDIRECT 0x0001 // 隐式处理重定向，
// 如果可能 [未实现]
WEBREQUEST_NOCOOKIES 0x0002 // 不处理 cookies；
 // 直接将标题传递给调用程序
// [未实现]
WEBREQUEST_NOCACHE 0x0004 // 将 "Pragma: no-cache" 发送给代理
// （如果使用代理）[未实现]
WEBREQUEST_NOKEEPALIVE 0x0008 // 禁用保持连接；强制实现
// 基本的 HTTP/1.0
WEBREQUEST_FORCENEWCONN 0x0010 // 强制进行新连接
WEBREQUEST_NOWAITCONN 0x0020// 不要等待可再次使用的
// 连接，强制进行新连接


有关 WEBOPT 使用期的重要信息

在发送响应回调之前，以上 WebOpts 列表中代表 pVals 的指针（如附加的标题字符串）必须保持有效。 除非选项列表中包含 WEBOPT_COPYOPTS，否则将不复制这些指针。

例如，不要使用类似以下示例的代码：

{
char szDateHeader[32];
SPRINTF(szDateHeader, "X-Date: %s\r\n", szToday);
IWEB_GetResponse(me->piWeb, (me->piweb,&me->cb,"http://www.somewhere.com/", WEBOPT_HEADER, szDateHeader,0));
}

由于 szHeader 处于堆栈上，在 IWeb 接口处理时不被复制，所以在函数返回时将以无效结束。 相反，请使用类似以下示例的代码：

typedef struct me
{
IWeb *piWeb;
AEECallback cb;
char szDateHeader[32]; // 完成 web 处理时，
// 在此保存数据
} me;
{
SPRINTF(me->szDateHeader, "X-Date: %s\r\n", szToday);
IWEB_GetResponse(me->piWeb, (me->piweb,&me->cb,"http://www.somewhere.com/", WEBOPT_HEADER, szDateHeader,0));
}

请勿使用类似以下示例的代码，这些代码会增加因内存不足而导致处理失败的可能：

{
char szDateHeader[32];
SPRINTF(szDateHeader, "X-Date: %s\r\n", szToday);
IWEB_GetResponse(me->piWeb, (me->piweb,&me->cb,"http://www.somewhere.com/", WEBOPT_HEADER, szDateHeader,TRUE,0));
}

在标题和状态回调的情况下，如果仍在进行的 Web 处理可能会用到回调或回调数据，则应特别注意保持这些回调和回调数据有效。 确保不违反这些规则的方法是，在应用程序的使用期仅保留并使用一个 IWeb 接口指针。

这将简化并进而保护您与 IWeb 接口及其回调的交互，并允许 IWeb 接口正确保持 HTTP 连接。在发送回调之前，IWebResp 返回值 (pWResp) 中将填写 IWebResp 接口指针。 发送回调后，IWEB_GetResponse() 的调用程序将负责调用 IWEBRESP_Release()。

另请参阅：

WebOpt

返回函数列表

IWEB_GetResponseV()

说明：

此函数是 IWEB_GetResponse() 的向量形式。

原型：

void IWEB_GetResponseV
(
IWeb * pIWeb,
IWebResp * * ppiwresp,
AEECallback * pcb,
const char * cpszUrl,
WebOpt * awozList
)

参数：

pIWeb | 指向 IWeb 接口对象的指针。
ppiwresp | 指向保存应答的 IWebResp 接口指针的指针。 对象必须在回调的使用期内有效。 完成后用户应将其释放。
pcb | 应答就绪时的调用位置。
cpszUrl | 请求的文档。
awozList | WebOpt 数组，以 WEBOPT_END 结束。

返回值：

无

备注：

无

另请参阅：

WebOpt

IWEB_GetResponse()

返回函数列表

IWEB_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IWEB_QueryInterface(IWeb * pIWeb, AEECLSID idReq, void * * ppo)

参数：

pIWeb | [in] | 指向 IWeb 接口对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [in/out] | 返回的对象。 由该函数填充。

返回值：

如果找到接口，则返回 SUCCESS。

如果内存不足，则返回 ENOMEMORY。

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT。

备注：

  • 如果 *ppo 为接口指针，则 *ppo 中的指针将被设置为新接口（同时增加 refcount ），如果对象不支持 ClassID，则将被设置为 NULL。
  • 如果 *ppo 为数据结构指针，则 *ppo 将被设置为 classID 提供的内部数据，如果对象不支持 classID，则将被设置为 NULL。

另请参阅：

无

返回函数列表

IWEB_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEB_AddRef()

返回函数列表

IWEB_RemoveOpt()

说明：

此函数用于删除索引为 nIndex，WebOpt ID 匹配 nOptId 的 WebOpt 选项。

原型：

int IWEB_RemoveOpt(IWeb * pIWeb, int32 nOptId, int32 nIndex)

参数：

pIWeb | 指向 IWeb 接口对象的指针。
nOptId | 要从选项列表中删除的选项的 ID。
nIndex | 具有相同 ID 的多个 Web 中将要删除的最近 IWEB_AddOpt() 选项索引。

返回值：

如果成功删除选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

IWEB_AddOpt()

返回函数列表


IWebOpts 接口

WebOpts（Web 选项）管理 API 用于操作 IWeb/配置。 IWebOpts 代表选项堆栈或列表，
这些选项可以为单值或多值。 IWebOpts 接口不强制单值或多值选项的语义。 选项堆栈的访问按添加选项的顺序进行。

例如按以下操作构成的列表：

AddOpt({OPT1, x}) ==> push {OPT1, x}
AddOpt({OPT1, y}) ==> push {OPT1, y}
AddOpt({OPT1, z}) ==> push {OPT1, z}
RemoveOpt(OPT1, 0) ==> 删除第 0 个 OPT1（即 {OPT1, z}）
AddOpt({OPT2, b},{OPT2, a})) ==> push {OPT2, a}，然后 push {OPT2, b}

将产生下列应答：

GetOpt(OPT1, 0) ==> 查找第 0 个 OPT1 => {OPT1, y}
GetOpt(OPT1, 1) ==> 查找第 1 个 OPT1 => {OPT1, x}
GetOpt(OPT1, 2) ==> 查找第 2 个 OPT1 => EFAILED
GetOpt(OPT1, 3) ==> 查找第 3 个 OPT1 => EFAILED
GetOpt(OPT2, 1) ==> 查找第 1 个 OPT2 => {OPT2, a}

IWebOpts 是 IWeb 和 IWebResp（均使用 IWebOpts 接口交流所有信息）的基类。

要包含的头文件列表

IWebOpts 需要以下头文件。

AEEWeb.h

函数列表

此接口的函数包括：

IWEBOPTS_AddOpt()

IWEBOPTS_AddRef()

IWEBOPTS_GetOpt()

IWEBOPTS_QueryInterface()

IWEBOPTS_Release()

IWEBOPTS_RemoveOpt()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IWEBOPTS_AddOpt()

说明：

此函数通过向当前 web 选项列表添加输入数组来添加 Web 选项列表。

原型：

int IWEBOPTS_AddOpt(IWebOpts * pIWebOpts, WebOpt * apwoz)

参数：

pIWebOpts | 指向 IWebOpts 接口对象的指针。
apwoz | WebOpt 结构数组，由 nId 设为 WEBOPT_END 的 WebOpt 终止。

返回值：

如果成功添加选项，则返回 SUCCESS。

如果未分配足够的内存，则返回 ENOMEMORY。

备注：

无

另请参阅：

WebOpt

IWEBOPTS_RemoveOpt()

IWEBOPTS_GetOpt()

返回函数列表

IWEBOPTS_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEBOPTS_Release()

返回函数列表

IWEBOPTS_GetOpt()

说明：

此函数用于在 IWebOpts 接口对象的 WebOpts 列表中查找 WebOpt ID 匹配 nOptId 的 WebOpt。 在多值 WebOpt 或覆盖的情况下，可能存在多个匹配。 这时，索引为 nIndex 的 WebOpt 选项将指定在匹配 WebOpt ID 的 WebOpts 列表中查找的距离。 pwo 参数中将填入匹配的 WebOpt 内容。 WebOpt 索引的初始值为零。

原型：

int IWEBOPTS_GetOpt
(
IWebOpts * pIWebOpts,
int32 nOptId,
int32 nIndex,
WebOpt * pwo
)

参数：

pIWebOpts | 指向 IWebOpts 接口对象的指针。
nOptId | 要在选项列表中查找的选项 ID，如果有，WEBOPT_ANY 将返回 nIndexth 选项。
nIndex | 具有相同 ID 的多个 WebOpt 中最近添加的 AddOpt() 选项索引。
pwo | 保存找到的 WebOpt 的位置。

返回值：

如果成功检索到选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

WebOpt

IWEBOPTS_AddOpt()

返回函数列表

IWEBOPTS_QueryInterface()

说明：

此函数继承于 IQI_QueryInterface()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IWEBOPTS_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEBOPTS_AddRef()

返回函数列表

IWEBOPTS_RemoveOpt()

说明：

此函数用于删除第 nIndex 个匹配 nOptId 的 WebOpt。

原型：

int IWEBOPTS_RemoveOpt(IWebOpts * pIWebOpts, int32 nOptId, int32 nIndex)

参数：

pIWebOpts | 指向 IWebOpts 接口对象的指针。
nOptId | 要从选项列表中删除的选项的 ID。
nIndex | 具有相同 ID 的多个 WebOpt 中将要删除的最近IWebOpts 接口 选项索引。

返回值：

如果成功删除选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

IWEBOPTS_AddOpt()

返回函数列表


IWebResp 接口

IWebResp 接口用于为响应端的 Web 处理提供资源。 该接口为 IWEB_GetResponse() 提供答案。 Web 处理结束时将通过指针创建并返回一个新的接口。 IWebResp 接口可运行头文件回调、提供消息主体，并通过 IWebOpts 接口告知有关 Web 处理的附加信息（另请参阅 IWeb 接口）。

要包含的头文件列表

需要以下头文件：

AEEWeb.h

函数列表

此接口的函数包括：

IWEBRESP_AddOpt()

IWEBRESP_AddRef()

IWEBRESP_GetInfo()

IWEBRESP_GetOpt()

IWEBRESP_QueryInterface()

IWEBRESP_Release()

IWEBRESP_RemoveOpt()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IWEBRESP_AddOpt()

说明：

此函数用于将 Web 列表添加至当前的 Web 选项集。

原型：

int IWEBRESP_AddOpt(IWebResp * pIWebResp, WebOpt * apwoz)

参数：

pIWebResp | 指向 IWebResp 接口对象的指针。
apwoz | WebOpt 结构数组，由 nId 设置为 WEBOPT_END 的 WebOpt 终止。

返回值：

如果成功添加选项，则返回 SUCCESS。

如果未分配足够的内存，则返回 ENOMEMORY。

备注：

无

另请参阅：

无

返回函数列表

IWEBRESP_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

IWEBRESP_Release()

BREW SDKTM AEE 分层结构图表

返回函数列表

IWEBRESP_GetInfo()

说明：

此函数用于返回与响应相关的预包装/解析的信息指针。

原型：

WebRespInfo * IWEBRESP_GetInfo(IWebResp * pIWebResp)

参数：

pIWebResp
指向 IWebResp 接口对象的指针。

返回值：

指向 WebRespInfo 的指针。

备注：

无

另请参阅：

WebRespInfo

返回函数列表

IWEBRESP_GetOpt()

说明：

此函数用于在 IWebOpts 接口对象的 WebOpts 列表中查找匹配 nOptId 的 WebOpt。 在多值 WebOpt 或覆盖的情况下，可能存在多个匹配。 这时，nIndex 将指定在匹配 nOptId 的 WebOpts 列表 中查找的距离。 pwo 参数中将填入匹配的 WebOpt 内容。nIndex 的起始值为零。

原型：

int IWEBRESP_GetOpt
(
IWebResp * pIWebResp,
int32 nOptId,
int32 nIndex,
WebOpt * pwo
)

参数：

pIWebResp | 指向 IWebResp 接口对象的指针。
nOptId | 要在选项列表中查找的选项的 ID，如果有，WEBOPT_ANY 将返回 nIndexth 选项。
nIndex | 最近添加至具有相同 ID 的多个 Web 的 AddOpt() 选项索引计数。
pwo | 保存找到的 WebOpt 的位置

返回值：

如果成功添加选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表

IWEBRESP_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IWEBRESP_QueryInterface
(
IWebresp * pIWebresp,
AEECLSID idReq,
void * * ppo
)

参数：

pIWebresp | [in] | 指向 IWebResp 接口对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [out] | 返回的对象。 由该函数填充。

返回值：

如果找到接口，则返回 SUCCESS

如果内存不足，则返回 ENOMEMORY

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT

备注：

  • 如果 *ppo 为接口指针，则 *ppo 中的指针将被设为新接口（同时增加refcount），如果对象不支持 ClassID，则将被设为 NULL。
  • 如果 *ppo 为数据结构指针，则 *ppo 将设置为 classID 所提供的内部数据，如果对象不支持 classID，则设置为 NULL。

另请参阅：

无

返回函数列表

IWEBRESP_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEBRESP_AddRef()

返回函数列表

IWEBRESP_RemoveOpt()

说明：

此函数用于删除索引为 nIndex，WebOpt ID 匹配 nOptId 的 WebOpt 选项。

原型：

int IWEBRESP_RemoveOpt(IWebResp * pIWebResp, int32 nOptId, int32 nIndex)

参数：

pIWebResp | 指向 IWebResp 接口对象的指针。
nOptId | 要从选项列表中删除的选项的 ID。
nIndex | 具有相同 ID 的多个 Web 中将要删除的最近 AddOpt() 选项索引。

返回值：

如果成功删除选项，则返回 SUCCESS。

如果未找到指定的 WebOpt，则返回 EFAILED。

备注：

无

另请参阅：

无

返回函数列表


IWebUtil 接口

此接口用于为 Web 处理提供实用函数（大多为无状态 API）。

要包含的头文件列表

需要以下头文件：

AEEWeb.h

函数列表

此接口的函数包括：

IWEBUTIL_AddRef()

IWEBUTIL_DecodeBase64()

IWEBUTIL_EncodeBase64()

IWEBUTIL_MakeUrl()

IWEBUTIL_ParseFormFields()

IWEBUTIL_ParseUrl()

IWEBUTIL_QueryInterface()

IWEBUTIL_Release()

IWEBUTIL_UrlDecode()

IWEBUTIL_UrlEncode()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IWEBUTIL_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEBUTIL_Release()

返回函数列表

IWEBUTIL_DecodeBase64()

说明：

此函数用于将 base64 编码的字符串解码到缓冲区。

原型：

int IWEBUTIL_DecodeBase64
(
IWebUtil * pIWebUtil,
const char * cpszIn,
char * pszOut
)

参数：

pIWebUtil | [in] | 指向 IWebUtil 接口 对象的指针。
cpszIn | [in] | 输入，base64 编码，以 NULL 结尾。
pszOut | [out] | 输出缓冲区。

返回值：

结果数据的长度；如果 Base64 字符串不正确，则返回 -1。

备注：

pszOut 参数必须足够长，以容纳所有的解码输出。 它也可以和 cpszIn 相同，在适当位置进行解码。

另请参阅：

AEEWEB_H

IWEBUTIL_EncodeBase64()

返回函数列表

IWEBUTIL_EncodeBase64()

说明：

此函数使用 base64 编码缓冲区。

原型：

char * IWEBUTIL_EncodeBase64
(
IWebUtil * pIWebUtil,
const char * cpcIn,
int nInLen,
char * pszOut
)

参数：

pIWebUtil | [in] | 指向 IWebUtil 接口对象的指针。
cpcIn | [in] | 输入/输出。
nInLen | [in] | cpcIn 的长度。
pszOut | [out] | 输出缓冲区。

返回值：

pszOut 输出缓冲区。

备注：

pszOut 参数必须至少分配 BASE64LEN(nInLen)，其中 nInLen 是输入数据的长度

另请参阅：

IWEBUTIL_DecodeBase64()

返回函数列表

IWEBUTIL_MakeUrl()

说明：

此函数可以根据 RFC2396 从基本 URL 和相对 URL 构建完整的 URL。

原型：

int IWEBUTIL_MakeUrl
(
IWebUtil * * pIWebUtil,
const char * cpszBase,
const char * cpszRel,
char * pResult,
int nResultLen
)

参数：

pIWebUtil | [in] 指向 IWebUtil 接口对象的指针。
cpszBase | [in] 以 NULL 结尾的基本 URL（可以是 NULL）。
cpszRel | [in] 以 NULL 结尾的相对 URL（可以是 NULL）。
pResult | [out] 构建完整 URL 的位置（可以是 NULL）。
nResultLen | [in] pResult 的大小（字节）。

返回值：

如果 pResult 非空，且 nResultLen 足够大（至少 STRLEN(pResult) +1）,则返回写入的字节数。

如果 pResult 为 NULL，或者 nResultLen 不够大，则返回构建 pResult 需要的字节数。

备注：

如果 pResult 非空，但结果无法容纳，则 pResult 将设为 ""。 参数 pResult 始终以 NULL 结尾。 构建完整 URL 需要的字节数可能大于结果的长度，因为此函数将使用分层 URL 的 "." 和 ".." 连接相对路径。

示例代码：

{
int nLen;
char * pResult;
nLen = IWEBUTIL_MakeUrl(pIWebUtil, cpszBase, cpszRel, 0, 0);
// 现在，nLen 保存着构建完整的 URL... 所需的大小
pResult = (char * )MALLOC(nLen);
nLen = IWEBUTIL_MakeUrl(pIWebUtil, cpszBase, cpszRel, pResult, nLen);
// 现在，nLen 保存 STRLEN(pResult) +1
}

另请参阅：

无

返回函数列表

IWEBUTIL_ParseFormFields()

说明：

此函数用于从“x-www-url 编码”字符串 *ppszIn 中解析出下一个 nMaxFields 形式字段，并将指向每个名称和值开头的指针存储在 awff 的连续元素中，然后将 ppszIn 推进至下一个未解析形式字段的开头。

“x-www-url 编码”形式字段字符串具有以下形式：

name1=value1&name2=value2&name3=value3& ...

或：

name1=value1;name2=value2;name3=value3; ...

其中名称和值部分不能包含 '='、';' 或 '&'，因此可以根据 RFC2936 由 URL 转码。

原型：

int IWEBUTIL_ParseFormFields
(
IWebUtil *pIWebUtil,
char **ppszIn,
WebFormField *awff,
int nMaxFields,
uint32 uFlags
)

参数：

pIWebUtil | [in] | 指向接口指针的指针
ppszIn | [in]/[out] | 指向名称值对的“x-www-url 编码”列表的指针，返回时设为下一个形式字段的开始位置。 ppszIn 和 *ppszIn 均不能为 NULL。
awff | [in]/[out] | 解析后要填充的 WebFormFields 数组，可能为 NULL
nMaxFields | [in] | awff 中的元素数量
uFlags | [in] | 0 或者 WEBUTIL_PFFF_NODECODE 与 WEBUTIL_PFFF_NOMUTATE 的逻辑“或”。WEBUTIL_PFFF_NODECODE － 禁止对 URL 的名称和值进行解码，并在 awff 中填入以 null 结束的原始值。如果您希望形式字段显示二进制数据（因为 NULL 可以编码为 %00），这将非常有用。WEBUTIL_PFFF_NOMUTATE － 禁止 URL 解码和以 null 结束，并在 awff 中填入指向 *ppszIn 的指针。调用程序将进行进一步的解析，把 ppszIn 设为下一个形式字段，但不修改 *ppszIn 指向的内存。

返回值：

成功解析的形式字段数，始终小于或等于 nMaxFields。

备注：

* 名称和值由 '=' 分隔，形式字段的名称或（和）值的长度可能为零。

例如：

"x=" 名称为 "x"，值的长度为零

"=y" 名称长度为零，值为 "y"

"=" 名称和值的长度均为零

"x" 名称为 "x"，值的长度为零

"" 不是形式字段，ParseFormField 将返回 0

* 形式字段由 '&' 或 ';' 分隔，IWEBUTIL_ParseFormFields() 将跳过空的形式字段（连续的分隔符和空字符串）：

"x=y&" 包含一个形式字段

"&x=y" 包含一个形式字段

"&&&x=y&&&w=z" 包含两个形式字段

"" 不包含形式字段

"&&&&&" 不包含形式字段

";;;;" 不包含形式字段

此 API 不区分 "x=" 和 "x"

如果传递的标记不是以上提供的标记，则 ParseFormFields() 的行为未定义

如果 awff 为 NULL，则依旧进行解析，并写入 ppszIn（除非传递 WEBUTIL_PFFF_NOMUTATE），*ppszIn 也仍设为下一个形式字段的起始位置。

要计数字符串中的形式字段，请调用 IWEBUTIL_ParseFormFields()，如下所示：

IWEBUTIL_ParseFormFields(pIWebUtil &pszQuery, // 要解析的字符串
0, // 请勿填写
((unsigned int)-1)>>1, // 无限制 (MAXINT)
WEBUTIL_PFFF_NOMUTATE);// 不破坏 pszQuery

另请参阅：

IWEBUTIL_UrlDecode()

WebFormField

返回函数列表

IWEBUTIL_QueryInterface()

说明：

此函数用于向对象请求其它的 API 合约。

原型：

int IWEBUTIL_QueryInterface
(
IWebUtil * pIWebUtil,
AEECLSID idReq,
void * * ppo
)

参数：

pIWebUtil | [in] | 指向 IWebUtil 接口对象的指针。
idReq | [in] | 对象显露的被请求 ClassID。
ppo | [out] | 返回的对象。 由该函数填充。

返回值：

如果找到接口，则返回 SUCCESS

如果内存不足，则返回 ENOMEMORY

如果不支持请求的接口，则返回 ECLASSNOTSUPPORT

备注：

  • 如果 *ppo 为接口指针，则 *ppo 中的指针将被设为新接口（同时增加refcount），如果对象不支持 ClassID，则将被设为 NULL。
  • 如果 *ppo 为数据结构指针，则 *ppo 将设置为 classID 所提供的内部数据，如果对象不支持 classID，则设置为 NULL。

另请参阅：

无

IWEBUTIL_ParseUrl()

说明：

此函数用于将 NULL 结尾的 URL 字符串解析为其组成部分。

原型：

int IWEBUTIL_ParseUrl
(
IWebUtil * pIWebUtil,
const char * cpszUrl,
UrlParts * pup
)

参数：

pIWebUtil | [in] 接口指针。
cpszUrl | [in] 以 NULL 结尾的待解析字符串。
pup | [out] 要填充的 UrlParts 结构指针。

返回值：

如果 URL 可以解析，则返回 SUCCESS。

否则，返回 EFAILED。

备注：

不得修改原始字符串。 指向原始字符串的指针将通过 UrlParts 结构返回。

另请参阅：

UrlParts

返回函数列表

IWEBUTIL_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IWEBUTIL_AddRef()

返回函数列表

IWEBUTIL_UrlDecode()

说明：

此函数用于解码 URL 编码字符串中的字符。

原型：

char * IWEBUTIL_UrlDecode
(
IWebUtil * pIWebUtil,
const char * cpcIn,
int * pnInLen,
char * pszOut,
int * pnOutLen
)

参数：

pIWebUtil | [in] | 指向 IWebUtil 接口对象的指针。
cpcIn | [in] | 指向待解码字节的指针。
pnInLen | [in/out] | cpcIn 的大小，返回时，设置为已用的字节数。
pszOut | [out] | 解码输出缓冲区。
pnOutLen | [in/out] | 输入时，pnOutLen 为 pszOut 的大小。 如果 pszOut 为 NULL，则 pnOutLen 将设为指定的缓冲区大小。 如果 pszOut 不为 NULL，pnOutLen 将设为解码数据的长度，如果解码后的 cpcIn 大小小于 pszOut， 则该长度可能小于 pszOut 的大小。

返回值：

pszOut 输出缓冲区。

备注：

无

另请参阅：

无

返回函数列表

IWEBUTIL_UrlEncode()

说明：

此函数用于根据 RFC2936 编码 URL 要包含的字符串中的字符。

原型：

char * IWEBUTIL_UrlEncode
(
IWebUtil * pIWebUtil,
const char * cpcIn,
int * pnInLen,
char * pcOut,
int * pnOutLen
)

参数：

pIWebUtil | [in] | 指向 IWebUtil 接口对象的指针。
cpcIn | [in] | 指向要编码的字符串的指针。
pnInLen | [in/out] | 指向 inLen 的指针，返回时设为成功编码的字节数。
pcOut | [out] | 写入编码字节的位置，可以是 NULL，用于计数。
pnOutLen | [in/out] | 输入时，pnOutLen 为 pcOut 的大小。 如果 pcOut 为 NULL，则 pnOutLen 将设为指定的缓冲区大小。 如果 pcOut 不为 NULL，pnOutLen 将设为编码数据的长度，如果无法容纳完整的编码字符或编码后的 cpcIn 大小小于 sizeof(pcOut)，则该长度可能小于 sizeof(pcOut)。

返回值：

pcOut，请参阅参数列表。

备注：

此函数将对 URL 中非法的或有句法意义的每个字符进行编码。但它并不用于完整的 URL，而只用在应当被忽略但可能存在非法 URL 处理的部分 URL 上（如 URL 的查询部分）。

该代码还可以用于编码形式内容（用于 HTTP 形式 POST 的主体）。

另请参阅：

无

返回函数列表


IX509Chain 接口

注意： IX509Chain 接口的实现和文档说明仅供参考。 由于尚未通过 QUALCOMM 正式测试，IX509Chain 接口至今未得到官方支持。

此接口用于管理和验证 X.509 证书链。

IX509Chain 接口可执行以下任务：

    • 管理证书存储，或调整存储方法
    • 允许访问证书的已解析字段，以显示给用户或其它访问者
    • 根据一组信任根和参数来验证证书链
    • 使用标准的 WebOpts 继承函数存储证书

使用 IX509Chain 接口

  1. 使用 IX509CHAIN_AddCert 或 IX509CHAIN_AddOpt 添加根证书、服务器证书和中间（分支）证书。
  2. 调用 IX509CHAIN_Verify 以查找信任链。
  3. 如果不是信任链，并且要覆盖它，请使用 AddOpt 添加 X509TrustOverride 记录。
  4. 使用 IX509CHAIN_GetBasic 或 IX509CHAIN_GetRSAKey 函数获取某些函数（例如加密会话密钥）所需要的公共密钥。

显示单个证书

  1. 首先必须标识证书本身，以便从集合中辨识。 这可以通过证书类型（根、分支或叶节点）和索引实现。 WebOpt id 提供证书类型（参见以下常量），WebOpt 索引提供证书索引。
  2. 接下来必须标识证书的字段。 例如，扩展、主题或序列号。 这可以隐含于调用 GetBasic 时返回的部分中；或者对于不适合堆栈，需要作为二进制 blob 处理的较大项目，通过向 GetField 或 GetFieldPart 传递字段的 ID 实现。 如果没有使用 GetFieldPart，则请跳过下一步。
  3. 接着，您必须给出签发者或主题部分的 OID，或扩展的 OID。 可以通过两种方法给出 OID：AEEASN1OIDS.h 中的预定义 ID，或者 DER/BER 编码 ANS.1 格式的完整 OID。
  4. 最后，您必须在所需字段中指定 OID 实例。 例如，您可能需要签发者字段中的第二个 OU（组织单元）。 您还可以遍历所有实例。
  5. 使用 "Get" 函数获取所需字段。

要包含的头文件列表

IX509Chain 需要以下头文件：

AEEX509Chain.h

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

函数列表

此接口的函数包括：

IX509Chain_AddCert()

IX509CHAIN_AddRef()

IX509CHAIN_AddOpt()

IX509CHAIN_GetBasic()

IX509CHAIN_GetField()

IX509CHAIN_GetFieldPart()

IX509CHAIN_GetOpt

IX509CHAIN_GetRSAKey()

IX509CHAIN_QueryInterface()

IX509CHAIN_Release()

IX509CHAIN_RemoveOpt()

IX509CHAIN_Verify()

IX509CHAIN_VerifyV()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表。

IX509Chain_AddCert()

说明：

此函数可以代替 IX509CHAIN_AddOpt() 来添加证书

原型：

int IX509CHAIN_AddCert
(
IX509Chain *pMe,
int32 nCertWebOpt,
const uint8 *pCert,
int nCertLen
);

参数：

pMe | 接口指针
nCertWebOpt | WEBOPT_X509_ROOT_CERT、_LEAF_CERT 或 _BRANCH_CERT
pCert | 指向缓冲区内 DER 编码证书的指针
nCertLen | 证书的长度

返回值：

SUCCESS

ENOMEMORY-由于内存不足而无法添加证书

EMEMPTR- 对象的 ASN.1/DER 长度大于 nCertLen。

备注：

使用 IX509CHAIN_AddOpt() 可直接添加 ASN.1/DER 格式化证书，但在添加时不会检查缓冲区长度是否正确。 而该接口将检查所添加对象的内部 ASN.1/DER 长度是否小于 nCertLen 中给定的长度。

ASN.1/DER 长度是指 pCert 中单个 ASN.1/DER 类型字节后面的 ASN.1/DER 编码长度。

为了能够对证书进行单独解析或者在验证操作中将其用作链部分，可以使用另一种方法添加证书，即将它们置于其它 IWebOpts 对象中，并将该对象作为默认对象添加到 IX509Chain 接口实例中。 （将接口指针作为 WEBOPT_DEFAULTS 类型添加）。 此外，所添加的 IWebOpt 对象不必完全实现 IWebOpts。

由于仅调用 IWEBOPTS_GetOpt() 函数，因此实现非常简单。

另请参阅：

无

返回函数列表。

IX509CHAIN_AddRef()

说明：

此函数继承于 IBASE_AddRef()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IX509CHAIN_Release()

返回函数列表。

IX509CHAIN_AddOpt()

说明：

此函数继承于 IWEBOPTS_AddOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IX509CHAIN_RemoveOpt()

返回函数列表。

IX509CHAIN_GetBasic()

说明：

此函数用于获取证书中基本字段和小字段

原型：

int IX509CHAIN_GetBasic
(
const IX509Chain *pMe,
int32 nCertWebOpt,
int32 nCertIndex,
X509BasicCert *pBasic
);

参数：

pMe | 接口指针
nCertWebOpt | 从中获取这些字段的 WebOpt id - WEBOPT_X509_ROOT_CERT、_LEAF_CERT 或 _BRANCH_CERT 或 .._CHAIN_CERT
nCertIndex | 给定 WebOpt ID 或类型的证书索引
pBasic | 放置所检索字段的位置。 提供存储的调用程序

返回值：

SUCCESS

EFAILED -无法找到证书

AEE_X509_BAD_CERT - 证书为 NULL 或无法解析

AEE_X509_UNKNOWN_KEY - 密钥类型未知（非 RSA）

AEE_X509_BAD_KEY - 无法解析密钥

AEE_X509_BAD_VALIDITY -有效日期错误

AEE_X509_NO_CHAIN_YET -在调用 IX509CHAIN_Verify 或添加任何叶节点之前尝试获取 WEBOPT_X509_CHAIN_CERT。它只返回遇到的第一个证书错误，尽管对于任意给定的证书可能存在多个问题。

备注：

X.509 解析程序为 X.509v3 手写代码。 它没有基于常规的 ASN.1 分析程序。 从正确的输入可以生成正确的结果。 但它不会验证数量极少的 ASN.1（ASN.1 语法非常冗长，因此可能进行大量的验证）。 对于未正确格式化的 ASN.1，它将不使用缓冲区，并且通常返回错误。 而它所返回的错误数据很少被呆板的 ASN.1 分析程序捕获。

日期的年份处理应符合 RFC 2549/3280 标准，并对 GeneralizedTime 中的数字年份进行处理。 UTCTime 中的两位数年份如果小于 50，将视为 2000 或 2000 年以后，如果大于或等于 50，则视为 1950 至 1999 年。

密钥存储的使用期限与 IX509Chain 相同，或者直至从链中将证书删除。

请注意，此分析程序有一个不明显的要求，即证书末尾的签名最小长度为 4 字节，否则该证书将被视为无效。

另请参阅：

无

返回函数列表。

IX509CHAIN_GetField()

说明：

此函数用于从 X.509 证书中获取字段。

原型：

int IX509CHAIN_GetField
(
const IX509Chain *pMe,
int32 nCertWebOpt,
int32 nCertIndex,
int nField,
const uint8 **ppcField,
uint32 *puFieldLen
);

参数：

pMe | 接口指针
nCertWebOpt | 从中获取这些字段的 WebOpt ID 集 - WEBOPT_X509_ROOT_CERT、_LEAF_CERT 或 _BRANCH_CERT
nCertIndex | 给定 WebOpt ID 或类型的证书索引
nField | 要获取的证书字段。 X509CHAIN_FIELD_* 之一
ppcField | 放置指向字段的指针的位置
puFieldLen | 字段长度的位置

返回值：

SUCCESS

EFAILED -无法找到证书

AEE_X509_BAD_CERT -证书为 NULL 或无法解析

ECLASSNOTSUPPORT-没有用于所请求散列的散列函数

ENOMEMORY - 内存不足（无法实例化散列函数）

EBADPARAM -所请求的字段不存在

AEE_X509_NO_CHAIN_YET -在成功调用验证之前尝试获取

WEBOPT_X509_CHAIN_CERT

备注：

该函数允许获取证书中的多数字段。 多数情况下，这些部分未解析。 例如，ASN.1 DER 编码日期、主题或密钥将返回未解析状态。 序列号已解析，并且只返回实际序列号。 字段存储的与 IX509Chain 的使用期限相同，或直到将证书从链中删除。 此函数还可以返回整个证书的 MD5 或 SHA1 散列。

另请参阅：

无

返回函数列表。

IX509CHAIN_GetFieldPart()

说明：

此函数用于获取单独的扩展，或者主题或发行者部分。

原型：

int IX509Chain_GetObjectPart
(
const IX509Chain *pMe,
const X509PartReq *pReq,
X509Part *pPart
);

参数：

pMe： X509Chain 实例

pReq： 请求说明

pPart： 填写响应。

返回值：

SUCCESS

EFAILED -无法找到证书

AEE_X509_BAD_CERT -证书为 NULL 或无法解析

EBADPARM -请求的字段未知

AEE_X509_NO_PART -无法找到所请求 OID 的实例

AEE_X509_NO_CHAIN_YET -在调用验证之前，

尝试获取 WEBOPT_X509_CHAIN_CERT

备注：

但是证书扩展与主体和发行者部分在语义上的关联不足，因此使用此函数来获取
它们。

以上数据结构说明描述了如何通过 OID 或 ASN1OID（已知 OID 的本地缩写）获取
不同部分。

密钥存储的使用期限与 IX509Chain 相同，或者直至从链中将证书删除。

这可以用来遍历字段中的所有部分或仅特定 OID 的值（如果恰好存在 OID 的多个实
例；主题或发行者中通常会复制 OU 部分）。 要进行遍历，请先获取字段中的第 0 个实例。 该响应将给出附加信息（即字段中的实例数目），由此可以知道遍历的距离。 您还可以遍历直至返回 EFAILED。 如果要查找字段中的所有部分，请传递 ASNOID_ANY 作为查找的 OID。

另请参阅：

返回函数列表。

IX509CHAIN_GetOpt

说明：

此函数继承于 IWEBOPTS_GetOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IX509CHAIN_GetRSAKey()

说明：

此函数用于获取 RSA 密钥，作为要使用的 IRSA 对象。

原型：

int IX509Chain_GetKey
(
const IX509Chain *pMe,
int32 nCertWebOpt,
int32 nCertIndex,
IRSA **ppiRSA
);

参数：

pMe | X509Chain 实例
nCertWebOpt | 从中获取这些字段的 WebOpt 集 - WEBOPT_X509_ROOT_CERT、_LEAF_CERT 或 _BRANCH_CERT
nCertIndex | 要获取的给定选项类型的证书索引
ppiRSA | 放置新创建 IRSA 接口指针的位置

返回：

SUCCESS

EFAILED -无法找到证书

AEE_X509_BAD_CERT -未正确解析证书

AEE_X509_NO_CHAIN_YET -在未调用 IX509CHAIN_Verify 之前或不存在叶节点证书的情况下，尝试获取 WEBOPT_X509_CHAIN_CERT

AEE_X509_BAD_KEY -无法解析密钥

AEE_X509_UNKNOWN_KEY -非 RSA 密钥

ENOMEMORY- 内存不足，无法存储密钥和实例化 IRSA

ECLASSNOSUPPORT- 此电话不支持任何 RSA 算法

EBADPARM-piRSA 中传递 null 指针对象

AEE_CRYPT_INVALID_KEY -密钥已解析，但仍旧存在问题

备注：

此函数通过实例化 IRSA 返回证书中的 RSA 密钥，以备使用。 完成后请务必释放 IRSA 实例。

另请参阅：

无

返回函数列表。

IX509CHAIN_QueryInterface()

说明：

这些是标准的继承入口点。 由于 IX509Chain 继承于 IWebOpt，因此可以使用 IQI_QueryInterface() 获取访问 IX509Chain 的 IWebOpts 接口。

另请参阅：

BREW SDKTM AEE 分层结构图表.

返回函数列表。

IX509CHAIN_Release()

说明：

此函数继承于 IBASE_Release()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IX509CHAIN_AddRef()

返回函数列表。

IX509CHAIN_RemoveOpt()

说明：

此函数继承于 IWEBOPTS_RemoveOpt()。

另请参阅：

BREW SDKTM AEE 分层结构图表.

IX509CHAIN_AddOpt()

返回函数列表。

IX509CHAIN_Verify()

说明：

此函数用于完成并验证证书链

原型：

void IX509Chain_Verify
(
IX509Chain *pMe,
509TrustResult *pTrustResult,
AEECallback *pVerifyCB,
...
);

参数：

pMe | X509Chain 实例
pTrustResult | 放置信任结果的位置。
pVerifyCB | 完成验证后进行回调。
... 选项列表 | 执行验证时使用的一组 web 选项

备注：

它将进行大量的密码分析，以验证实际证书上的签名，直至验证根集中的根。 根据密钥长度、密钥模数、处理器速度和证书链长度，该操作所需的时间各不相同。 对于多数证书链只需要几秒钟。

首先构建证书链。 这可以通过查找叶节点证书并搜索主题与发行者相匹配的证书来实现。 搜索在选项树上进行，首先搜索命令行传递给“验证”操作的选项，接着搜索实例自身存储的选项，然后搜索所有默认选项集中的选项。 搜索始终从根证书开始，然后搜索分支证书。选项树中先添加的证书先匹配。 构成证书链时，需要比较发行者与主题。

发行者识别名 (DN) 与主题 DN 之间的比较应遵循 RFC 2459 / 3280 第 6.1 节和 X.509 第 9 节。它将忽略 PrintableString 类型的属性值 (AV) 的前导或后缀空格以及大小写，并对其它所有 AV 进行二进制比较。 它对组成 DN 的相对识别名 RDN 的结构/顺序很敏感，但对 DN 中的 AV 顺序没有要求。

因此，以下各项均相等：

1) (O=fish-tacos, OU=fish, OU=halibut), (CO=mexico,ST=baja)

2) (OU=halibut,O=fish-tacos, OU=fish) (ST=baja,CO=mexico)

但下面各项彼此不等，与上述各项也不相等：

3) (CO=mexico), (ST=baja), (OU=halibut), (O=fish-tacos, OU=fish)

4) (O=fish-tacos, OU=fish), (OU=halibut), (CO=mexico), (ST=baja)

构成链以后，将复制是链部分，但未存储在 IX509Chain 实例中的证书。 因此，该链在完成验证后仍将保留，以便执行显示等操作。

然后对链进行验证。 这包括验证分节点证书是否匹配主机名，然后验证每个证书上的有效日期、扩展约束以及签名。 该验证不会在出现第一个错误时停止。 它将持续验证整个已计算的证书链。

其间错误将在响应结构的位映射中累计。 所有这些错误都是可以覆盖的“软”信任错误。 硬错误主要是指内存不足或缺少有效的叶节点证书。 单个证书可以禁用或覆盖验证，整个链也可以通过 TrustOverride 记录来禁用或覆盖验证。

主机名、TrustOverride 记录和其它选项均存储在 WebOpts 中，而 WebOpts 可以存储在实例本身中或传递到命令行。 请注意，通过传递 IWebOpt 实例作为新的默认值，可将整个选项树传递到命令行。

完成验证后，调用回调。 通过对传递到验证操作的回调记录调用 CALLBACK_Cancel，可以取消验证操作。 请注意，释放 IX509Chain 对象并没有取消回调。 该对象仍然存在，并将完成回调。 因此必须在释放 IX509Chain 对象之前取消回调（除非您想要在释放后调用回调）。 另请注意，对同一 IX509Chain 对象的两个验证操作可能同时开始（尽管不能确定是否有效）。

将结果复制到 pTrustResult 结构中。 调用验证后，您可以使用 WEBOPT_X509_CHAIN_CERT 选项类型按照链顺序获取证书。 通常，该排序在调用 RemoveOpt 后将失效，此后直到再次调用验证时才能保证其有效性。

请注意，如果通过添加或删除叶节点和分支证书重用此对象来验证多个链，则在将根作为选项参数传递时，复制的根数量将会增加。

基本约束扩展的处理方法如下： 如果扩展未标记为“关键”或者是叶节点证书部分，则它将被完全忽略。 否则，cA 布尔值必须为 true，且扩展中的 pathLen 将受到限制。 如果 cA 布尔值为 false，则给出 X509CHAIN_BASIC_CONST。 如果 pathLen 过长，则给出 X509CHAIN_LONG_CHAIN。 要禁用所有基本约束处理，请设置 X509CHAIN_BASIC_CONST 作为覆盖。

X509v3 密钥使用扩展的处理方法如下所示。 如果扩展未标记为“关键”，则它将被完全忽略。 如果它出现在分支或根（不是叶节点）中，并且为“关键”，则它必须包含 ASNOID_KEYUSE_CERTSIGN，否则将给出信任错误 X509CHAIN_KEY_USE。 如果它出现在叶节点证书中，则对于选项 WEBOPT_X509_KEY_USE 中设置的每个使用位，扩展中必定存在匹配值，否则将设置信任错误 X509CHAIN_KEY_USE。 X509v3 扩展密钥使用扩展的处理方法如下所示。 不论它是否标记为“关键”都需要处理。 如果它出现在根或分支证书（不是叶节点）中，并且为“关键”，则将设置 X509CHAIN_EXT_KEY_USE 错误。 如果它出现在叶节点证书中，则对于选项 WEBOPT_X509_EXT_KEY_USE 中给出的每个使用位，扩展中必定存在匹配值，否则将设置 X509CHAIN_CRIT EXT_KEY_USE。 如果它出现在叶节点证书上并标记为“关键”，则将设置 X509CHAIN_CRIT_EXT_KEY_USE 错误。 要覆盖所有处理，请设置 X509CHAIN_CRIT_EXT_KEY_USE。

要在它不是“关键”时才覆盖，请设置 X509CHAIN_EXT_KEY_USE。 证书中还有其它类型的扩展。 它们全部被忽略。 如果愿意，您可以使用 IX509Chain_GetFieldPart 函数获取并处理这些扩展。 如果扩展标记为“关键”且未知，则将设置 X509CHAIN_CRITICAL_EXTENSION。endif /* AEEX509Chain_H

另请参阅：

无

返回函数列表。

IX509CHAIN_VerifyV()

说明：

此函数用于完成并验证证书链

原型：

void IX509Chain_VerifyV
(
IX509Chain *pMe,
X509TrustResult *pTrustResult,
AEECallback *pVerifyCB,
const WebOpt *awozList
);

参数：

pMe | X509Chain 实例
pTrustResult | 放置信任结果的位置。
pVerifyCB | 完成验证后进行回调。
awozList | 执行验证时使用的 web 选项组

备注：

请参阅 IX509CHAIN_Verify() 中"备注： "下的论述

另请参阅：

无

返回函数列表。


SSLRootCerts 接口

此接口提供对一组嵌入的常用根证书的访问。 它的不寻常在于，它并非是一个属于自己的新接口。 它的接口就是 IWebOpts 接口 接口。 不同之处在于一组预设的包含常用根证书的选项。 它们将 WebOpt.nID 设置为 WEBOPT_X509_ROOT_CERTS，选项数量通常为五个或十个。

调用 ISHELL_CreateInstance() 时，传递 AE ECLSID_SSLROOTS 作为类 ID，您将获得 IWebOpts *。 您可以将它用作 IWebOpts 的一个完整实例，并根据需要存储其它内容。

可用根证书通常是常用的 VeriSign 根。 它们可以提供方便并节省手持设备上的空间，并且它们仅保留一个副本，而不是在每个使用 SSL 的应用程序中都保留副本。 手持设备仅包含常用根证书的一小部分，从而防止占用过多的空间。

这些通常会被实例化，并传递至 IX509CHAIN_Verify()、ISSL_Negotiate() 或 IWEB_GetResponse()，作为 WEBOPT_DEFAULTS 类型的选项。

要包含的头文件列表

需要以下头文件：

AEESSL.h

函数列表

该接口的函数包括：

无

有关详细信息，请参阅BREW SDKTM AEE 分层结构图表。


助手函数

本部分提供 AEE 的各类助手函数的文档资料。 包括字符串函数、标准 C 库函数、实用函数和其它项目。 标准 C 库函数是指 C/C++ 编译器/IDE 提供的 ANSI 标准 C 库。 应用程序不可以直接调用标准 C 库函数（如 memcpy）， 而必须使用 AEE 提供的函数（如 MEMCPY()）。 此处说明的函数与 AEE 其它函数的区别在于访问这些函数不需要接口指针。 例如，调用函数 MEMCPY() 时，不需要接口指针， 应用程序可以直接调用 MEMCPY()。 此处提供的某些函数可直接调用标准 C 库函数（例如，MEMCPY() 函数可直接调用 C 库函数 memcpy()）。 提供这些函数有以下两个原因：

  • 消除每个应用程序都与标准 C 库静态连接的必要。 如果在设备上加载多个应用程序，每个应用程序都有包含标准 C 库的额外负担。 要避免发生此情况，AEE 保留了标准 C 库的单一拷贝， 所有的应用程序都可使用该拷贝。 应用程序不允许直接调用标准 C 库函数（因此，避免了给应用程序增加静态 C 库的负担）。
  • 使用不具有任何相关静态数据的动态应用程序。 如果应用程序要直接调用标准
    C 库函数如 memcpy()，则需要包括相应的头文件（如 memory.h）。 这些头文件库可能包含静态数据。 如果包含，则使用标准 C 库函数将使应用程序无法动态加载。

由于上述原因，AEE 提供助手函数，其中一些是能够直接调用标准 C 库函数的包装函数。

要包含的头文件列表

需要以下头文件：

AEEStdLib.h

函数列表

此接口的函数包括：

AEE_GET_X()

AEE_GET_Y()

AEE_HI()

AEE_LO()

AEE_SET_XY()

ATOI()

CALLBACK_Cancel()

CALLBACK_Init()

CALLBACK_IsQueued()

CONVERTBMP()

CREATEOBJ()

DBGPRINTF()

FADD()

FASSIGN_INT()

FASSIGN_STR()

FCMP_E()

FCMP_G()

FCMP_GE()

FCMP_L()

FCMP_LE()

FDIV()

FLOAT_TO_WSTR()

FLOATTOWSTR()

FMUL()

FREE()

FREEIF()

FREEOBJ()

FSUB()

GET_APP_INSTANCE()

GET_JULIANDATE()

GET_NOTIFIER_MASK()

GET_NOTIFIER_VAL()

GET_RAND()

GET_SECONDS()

GET_TIMEMS()

GET_UPTIMEMS()

GETAEEVERSION()

GETAPPINSTANCE()

GETCHTYPE()

GETJULIANDATE()

GETRAND()

GETTIMEMS()

GETTIMESECONDS()

GETTLS

GETUPTIMEMS()

HTOLEL()

HTOLES()

HTONL()

HTONS()

INET_ATON()

INET_NTOA()

JULIANTOSECONDS()

LETOHL()

LETOHS()

LOCALTIMEOFFSET()

LOCKMEM()

MAKE_RGB()

MALLOC()

MALLOCREC()

MALLOCREC_EX()

MEMCHR()

MEMCHREND()

MEMCMP()

MEMCPY()

MEMMOVE()

MEMRCHR()

MEMRCHRBEGIN()

MEMSET()

MEMSTR()

NTOHL()

NTOHS()

OEMSTRLEN()

OEMSTRSIZE()

REALLOC()

SETAEERECT()

SETSTACKBOTTOM

SETSTATICPTR

SETTLS

SPRINTF()

STR_TO_WSTR()

STRBEGINS()

STRCAT()

STRCHR()

STRCHREND()

STRCHRSEND()

STRCMP()

STRCPY()

STRDUP()

STRENDS()

STREXPAND()

STRICMP()

STRISTR()

STRLCAT()

STRLCPY()

STRLEN()

STRLOWER()

STRNCMP()

STRNCPY()

STRNICMP()

STRRCHR()

STRSTR()

STRTOUL()

STRTOWSTR()

STRUPPER()

SYSFREE()

UNLOCKMEM()

UTF8_TO_WSTR()

UTF8TOWSTR()

VSNPRINTF()

VSPRINTF()

WEB_ERROR_MAP()

WEB_ERROR_SUCCEEDED()

WSPRINTF()

WSTR_TO_FLOAT()

WSTR_TO_STR()

WSTR_TO_UTF8()

WSTRCAT()

WSTRCHR()

WSTRCMP()

WSTRCOMPRESS()

WSTRCPY()

WSTRDUP()

WSTRLCAT

WSTRLCPY()

WSTRLEN()

WSTRLOWER()

WSTRNCMP()

WSTRNCOPYN()

WSTRRCHR()

WSTRSIZE()

WSTRTOFLOAT()

WSTRTOSTR()

WSTRTOUTF8()

WSTRUPPER()

WWRITELONG()

WWRITELONGEX()

ZEROAT()

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

AEE_GET_X()

说明：

此函数是用于从给定的 32 位 dwParm 中提取 x 坐标值的宏。 它与 AVK_TAP 按键代码一起使用。 发生 TAP 点击时，应用程序将收到 EVT_KEY 事件，其 wParam 设置为 AVK_TAP，并且 dwParm 中包含 tap 点击位置的 x 和 y 坐标。 dwParm 的高 16 位包含点击的 x 坐标，而低 16 位包含 y 坐标。 AEE_GET_X() 宏可用于获取 tap 点击的
x 坐标。 在 SDK 中，在模拟设备的屏幕部分单击鼠标时会收到相同的事件。

原型：

uint16 AEE_GET_X(uint32 dwParm)

参数：

dwParm
包含点击的 x 和 y 坐标的 32 位值。

返回值：

TAP 点击的 X 坐标

备注：

无

另请参阅：

AEE_GET_Y()

返回函数列表

AEE_GET_Y()

说明：

此函数是用于从给定的 32 位 dwParm 中提取 y 坐标值的宏。 它与 AVK_TAP 按键代码一起使用。 发生 TAP 点击时，应用程序将收到 EVT_KEY 事件，其 wParam 设置为 AVK_TAP，并且 dwParm 中包含 tap 点击位置的 x 和 y 坐标。 dwParm 的高 16 位包含点击的 x 坐标，而低 16 位包含 y 坐标。 AEE_GET_Y() 宏可用于获取 tap 点击的
y 坐标。 在 SDK 中，在模拟设备的屏幕部分单击鼠标时会收到相同的事件。

原型：

uint16 AEE_GET_Y(uint32 dwParm)

参数：

dwParm
包含点击的 x 和 y 坐标的 32 位值。

返回值：

TAP 点击的 Y 坐标

备注：

无

另请参阅：

AEE_GET_X()

返回函数列表

AEE_HI()

说明：

此函数是用于从给定的 32 位值中提取高 16 位的宏。

原型：

uint16 AEE_HI(uint32 dwParm)

参数：

dwParm
需要提取其高 16 位的 32 位值。

返回值：

给定 32 位值的高 16 位。

备注：

无

另请参阅：

AEE_LO()

返回函数列表

AEE_LO()

说明：

此函数是用于从给定的 32 位值中提取低 16 位的宏。

原型：

uint16 AEE_LO(uint32 dwParm)

参数：

dwParm
需要提取其低 16 位的 32 位值。

返回值：

给定 32 位值的低 16 位。

备注：

无

另请参阅：

AEE_HI()

返回函数列表

AEE_SET_XY()

说明：

此函数是用于将 x 和 y 坐标值置于 x 中的宏。它先将 x 的当前值左移 16 位，然后将
y 值置于 x 的低 16 位。

原型：

void AEE_SET_XY(uint32 x, uint16 y)

参数：

x | 最终包含 x 和 y 值的 32 位值
Y | 必须置于 x 低位字中的 16 位值。

返回值：

无

备注：

无

另请参阅：

AEE_GET_X()

返回函数列表

ATOI()

说明：

此函数是标准 C 库提供的 ATOI() 函数的包装，其行为与 ATOI() 相同。 它用于将输入字符串转换为整型数。

原型：

int ATOI(const char * src)

参数：

src
指向源字符串的指针。

返回值：

输入字符串代表的整型数。

备注：

无

另请参阅：

无

返回函数列表

CALLBACK_Cancel()

说明：

此函数用于取消以前通过 ISHELL_Resume() 注册的回调，但只能在回调未发生时将其取消。 要检查是否已经发生回调，请查看 AEECallback 结构中的 pfnCancel 成员是否为 NULL。 如果 AEE 已将其设为 NULL，则不能取消。

原型：

void CALLBACK_Cancel(AEECallback * pcb)

参数：

pcb
指向已使用 ISHELL_Resume() 注册的 AEECallback 结构的有效指针。

返回值：

无

备注：

无

另请参阅：

AEECallback

ISHELL_Resume()

返回函数列表

CALLBACK_Init()

说明：

此函数用于初始化 AEECallback 结构的成员。

原型：

void CALLBACK_Init(AEECallback * pcb, PFNNOTIFY pfn, void * pd)

参数：

pcb | 指向必须初始化的 AEECallback 结构的有效指针。
pfn | 指向回调函数的有效指针。
pd | 指向调用 pfn 函数时必须向它传递的数据的指针。

返回值：

无

备注：

无

另请参阅：

AEECallback

PFNNOTIFY

ISHELL_Resume()

返回函数列表

CALLBACK_IsQueued()

说明：

此函数用于检查通过 ISHELL_Resume() 注册的回调是否仍在排队等待处理。
如果已发生回调或已使用函数 CALLBACK_Cancel() 将其取消，则回调将不再排队。

原型：

boolean CALLBACK_IsQueued(AEECallback * pcb)

参数：

pcb
指向已使用 ISHELL_Resume() 注册的 AEECallback 结构的指针。

返回值：

如果回调仍在排队等待处理，则返回 TRUE。

否则，返回 FALSE。

备注：

如果回调不再排队，pcb 所引用的 AEECallback 结构的 pfnCancel 成员将为 NULL。 此函数检查 pcb->pfnCancel 是否为 NULL 以确定回调是否排队。

另请参阅：

ISHELL_Resume()

返回函数列表

CONVERTBMP()

说明：

此函数用于将 Windows 位图转换为本地格式。 本地格式是指每种设备特有的格式。 在 Windows 上，本地格式与 Windows 位图格式相同。 例如，如果用户拥有包含 Windows 位图的原始数据缓冲区，可将其传递给此函数并转换为本地格式，以便对此格式使用 IDISPLAY_BitBlt() 函数来显示图像。 BREW Emulator 不支持 16 位和 24 位 BMP 文件格式。

原型：

void * CONVERTBMP
(
void * pSrcBuffer,
AEEImageInfo * pii,
boolean * pbRealloc
)

参数：

pSrcBuffer | [in] | 指向包含 Windows 位图的缓冲区的指针。 构造方法之一是将 Windows BMP 文件的内容读入内存缓冲区。 返回时该缓冲区将转换为本地格式。
pii | [out] | 返回时，该成员所指的 AEEImageInfo 结构将包含有关已转换图像的有效信息（如宽度、高度、颜色深度及其它）。
pbRealloc | [out] | 返回时，根据 CONVERTBMP() 函数是否为此函数所返回的缓冲区单独分配内存，将其设置为 TRUE 或 FALSE。 如果设为 TRUE，则在使用此函数返回的缓冲区后，调用程序必须通过 SYSFREE() 将其释放。

返回值：

包含已转换图像的有效缓冲区。 它是已转换为本地格式的输入图像 pSrcBuffer。 如果返回时将 pbRealloc 设置为 true，则在使用缓冲区后调用程序必须通过 SYSFREE() 将其释放。 在 Windows 上，由于本地格式与 BMP 格式相同，所以函数返回的指针也与 pSrcBuffer 相同。 另外，由于没有进行新的分配，在 Windows 上，bRealloc 将为 FALSE。 pii 参数返回时将包含有关图像的信息（例如宽度、高度、颜色深度和其它）。

如果失败，则返回 NULL。

备注：

无

另请参阅：

AEEImageInfo

返回函数列表

CREATEOBJ()

说明：

此函数是 MALLOC() 的别名。

原型：

void * CREATEOBJ(DWORD dwSize)

参数：

dwSize
指定必须分配的大小（字节）。

返回值：

指向大小为 dwSize 字节的缓冲区的指针。

如果失败，则返回 NULL。

备注：

无

另请参阅：

MALLOC()

返回函数列表

DBGPRINTF()

说明：

此函数用于打印输出调试信息。

注意： 扩展字符串（包括格式字符串）的总长度不应超过 127 个字节。 如果扩展字符串的总长度超过 128 个字节，则可能截断该字符串，否则将导致严重错误。

在手持设备上运行时，只显示前 63 个字节；忽略前 63 个字节之后的所有字节。

原型：

void DBGPRINTF(const char *pszFormat,...)

参数：

pszFormat
格式控件字符串，请参考相应平台 (Windows / ARM) 上标准 C 库函数 printf() 的文档

返回值：

无

备注：

无

另请参阅：

SPRINTF()

VSPRINTF()

VSNPRINTF()

WSPRINTF()

返回函数列表

FADD()

说明：

此函数用于执行浮点加法运算。

原型：

double FADD(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

返回加法的结果。

备注：

无

另请参阅：

无

返回函数列表

FASSIGN_INT()

说明：

此函数用于返回双精度实数，其值由输入串指定。

原型：

double FASSIGN_INT(int32 val)

参数：

val
为返回的双精度实数指定的值。

返回值：

返回具有指定值的双精度实数

备注：

这是一种使用整型变量初始化浮点变量的简单方法。

例如，

FASSIGN_INT(3)

将返回值为 3.0 的双精度实数

另请参阅：

无

返回函数列表

FASSIGN_STR()

说明：

此函数用于返回双精度实数，其值由输入字符串指定。

原型：

double FASSIGN_STR(char *pszFloat)

参数：

pszFloat
包含指定值的字符串

返回值：

返回具有指定值的双精度实数

备注：

这是一种初始化浮点变量的简单方法。

例如

FASSIGN_STR("3.1416")

将返回值为 3.1416 的双精度实数

注意：在 BREW 模块中，类似 double f = 3.1416 的赋值操作将导致连接问题，因此该机制非常适用。

另请参阅：

无

返回函数列表

FCMP_E()

说明：

此函数用于执行浮点“等于”比较。

原型：

boolean FCMP_E(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

如果 v1 == v2，则返回 TRUE。

如果 v1 != v2，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

FCMP_G()

说明：

此函数用于执行浮点“大于”比较。

原型：

boolean FCMP_G(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

如果 v1 > v2，则返回 TRUE。

如果 v1 <= v2，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

FCMP_GE()

说明：

此函数用于执行浮点“大于或等于”比较。

原型：

boolean FCMP_GE(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

如果 v1 >= v2，则返回 TRUE。

如果 v1 < v2，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

FCMP_L()

说明：

此函数用于执行浮点“小于”比较。

原型：

boolean FCMP_L(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

如果 v1 < v2，则返回 TRUE。

如果 v1 >= v2，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

FCMP_LE()

说明：

此函数用于执行浮点“小于或等于”比较。

原型：

boolean FCMP_LE(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

如果 v1 <= v2，则返回 TRUE。

如果 v1 > v2，则返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

FDIV()

说明：

此函数用于执行浮点除法运算。

原型：

double FDIV(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

返回除法运算的结果。

备注：

无

另请参阅：

无

返回函数列表

FLOAT_TO_WSTR()

注意：建议不使用此函数， 而使用 FLOATTOWSTR()。

说明：

此函数用于将浮点值转换为宽字符串。 在内部，该函数首先使用标准 C 库函数 sprintf() 将给定的浮点值转换为单字节字符串， 然后使用 STR_TO_WSTR() 将单字节字符串转换为宽字符串。

原型：

boolean FLOAT_TO_WSTR(double v, AECHAR * psz, int nSize)

参数：

v | 必须转换为宽字符串的浮点值。
psz | 指向保存结果宽字符串的宽字符串缓冲区的指针。
nSize | psz 缓冲区的大小（字节）。

返回值：

如果成功，则返回 TRUE。

如果失败、psz 为 NULL 或 nSize <为 0，则返回 FALSE。

备注：

无

另请参阅：

WSTR_TO_FLOAT()

返回函数列表

FLOATTOWSTR()

说明：

此函数用于将浮点值转换为宽字符串。 在内部，该函数首先使用标准 C 库函数 sprintf() 将给定的浮点值转换为单字节字符串， 然后使用 STRTOWSTR() 将单字节字符串转换为宽字符串。

原型：

boolean FLOATTOWSTR(double v, AECHAR * psz, int nSize)

参数：

v | 必须转换为宽字符串的浮点值。
psz | 指向保存结果宽字符串的宽字符串缓冲区的指针。
nSize | psz 缓冲区的大小（字节）。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

WSTRTOFLOAT()

返回函数列表

FMUL()

说明：

此函数用于执行浮点乘法运算。

原型：

double FMUL(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

返回乘法运算的结果。

备注：

无

另请参阅：

无

返回函数列表

FREE()

说明：

此函数对应于标准 C 库中的 free()。

原型：

void FREE(void * po)

参数：

po
指向要释放的内存。

返回值：

无

备注：

无

另请参阅：

FREEIF()

MALLOC()

REALLOC()()

返回函数列表

FREEIF()

说明：

此函数是 FREE() 的别名，带有 NULL 指针保护。

原型：

void FREEIF(void * p)

参数：

p
指向使用 MALLOC 或类似函数分配的释放缓冲区的指针。

返回值：

无

备注：

此函数有助于避免双重释放。

副作用：

返回时 p 设为 NULL。

另请参阅：

FREE()

返回函数列表

FREEOBJ()

说明：

此函数是 FREE() 的别名。

原型：

void FREEOBJ(void * pObj)

参数：

pObj
指向必须释放的内存缓冲区的指针。 该缓冲区必须是使用 CREATEOBJ() 分配的缓冲区。

返回值：

无

备注：

无

另请参阅：

FREE()

返回函数列表

FSUB()

说明：

此函数用于执行浮点减法运算。

原型：

double FSUB(double v1, double v2)

参数：

v1 | 操作数 #1。
v2 | 操作数 #2。

返回值：

减法运算的结果。

备注：

无

另请参阅：

无

返回函数列表

GET_APP_INSTANCE()

建议不使用此函数。 请使用 GETAPPINSTANCE()

说明：

此函数用于返回当前正在执行的小程序的 IApplet 实例。 它在所有的 BREW API 调用、回调和事件中均有效。

原型：

IApplet * GET_APP_INSTANCE(void)

参数：

无

返回值：

返回指向当前正在执行的小程序的 IApplet 指针。

备注：

无

另请参阅：

无

返回函数列表

GET_JULIANDATE()

建议不使用此函数。 请使用 GETJULIANDATE()

说明：

此函数可依据输入的秒数填充 JulianType 数据结构。 该值表示从 1980 年 1 月 6 日 00:00:00 GMT（设备参考时间）起至今的秒数。 如果输入值为 0（零），则返回当前的系统时间。

原型：

void GET_JULIANDATE(uint32 dwSecs, JulianType * pDate)

参数：

dwSecs | 1980 年 1 月 6 日 GMT（设备参考时间）至今经过的秒数。
pDate | 指向返回时需要填充的结构的指针。

返回值：

无

备注：

在 Windows 上，dwSecs 的上限是设备参考时间 1980 年 1 月 6 日 00:00:00 GMT 和 PC 参考时间 1970 年 1 月 1 日 00:00:00 的差与 uint32 允许的最大值之间的差额。

另请参阅：

JulianType

GETJULIANDATE()

GET_SECONDS()

GET_TIMEMS()

GET_UPTIMEMS()

GETTIMESECONDS()

GETTIMEMS()

GETUPTIMEMS()

返回函数列表

GET_NOTIFIER_MASK()

说明：

此函数用于从指定的 32 位通知掩码返回“掩码值”（低 16 位）。

原型：

uint16 GET_NOTIFIER_MASK(uint32 dwMasks)

参数：

dwMasks
32 位通知掩码。

返回值：

掩码值（低 16 位）

备注：

无

另请参阅：

无

返回函数列表

GET_NOTIFIER_VAL()

说明：

此函数用于从指定的 32 位通知掩码返回“通知匹配值”（高 16 位）。

原型：

uint16 GET_NOTIFIER_VAL(uint32 dwMasks)

参数：

dwMasks
32 位通知掩码。

返回值：

通知匹配值（高 16 位）

备注：

无

另请参阅：

无

返回函数列表

GET_RAND()

注意：建议不使用此函数， 而使用 GETRAND()。

说明：

此函数使用设备的随机数发生器，向输入缓冲区填充随机值数组。

原型：

void Get_Rand(byte * pDest, int nSize)

参数：

pDest | 指向目标缓冲区的指针。
nSize | 缓冲区的大小（字节）。

返回值：

无

备注：

此函数使用设备的随机数发生器，向输入缓冲区填充一系列随机字节。 该序列会在当前时间形成种子值，所以，除非间隔至少几毫秒，否则多次调用会得到相同的结果。 要获得最佳结果，可在每次调用事件处理函数时调用一次该函数。

另请参阅：

无

返回函数列表

GET_SECONDS()

注意：建议不使用此函数， 而使用 GETTIMESECONDS()。

说明：

此函数用于返回从 1980 年 1 月 6 日 00:00:00 GMT 至今的秒数（已调整为当地时间）。

原型：

uint32 GET_SECONDS()

参数：

无

返回值：

1980 年 1 月 6 日 00:00:00 GMT 至今经过的时间。

备注：

无

另请参阅：

GET_JULIANDATE()

GET_TIMEMS()

GET_UPTIMEMS()

返回函数列表

GET_TIMEMS()

注意：建议不使用此函数， 而使用 GETTIMEMS()。

说明：

此函数用于返回当前时间（毫秒）。 该调用的返回值取决于设备的当前时间值。
在设备上，该值是从基站获取，设备首次获取系统覆盖时该值可能有较大的变化。

原型：

uint32 GET_TIMEMS()

参数：

无

返回值：

从午夜开始经过的毫秒数。

备注：

无

另请参阅：

GET_JULIANDATE()

GET_SECONDS()

GET_UPTIMEMS()

返回函数列表

GET_UPTIMEMS()

注意：建议不使用此函数， 而使用 GETUPTIMEMS()。

说明：

此函数用于返回设备开机后经过的时间（毫秒）。 它与 GET_TIMEMS() 不同，其返回值不会因初次获取系统覆盖范围而发生较大的变化。

原型：

uint32 GET_UPTIMEMS()

参数：

无

返回值：

设备开机后经过的时间（毫秒数）。

备注：

在 Emulator 中，此函数返回 Emulator 选择当前设备配置后经过的时间（毫秒数）。

另请参阅：

GET_TIMEMS()

GET_SECONDS()

GET_JULIANDATE()

返回函数列表

GETAEEVERSION()

说明：

此函数用于获取有关当前正在使用的 BREW 软件的版本号信息。 版本号以 w.x.y.z 格式保存，其中：

w：指示主版本号

x：指示次版本号

y：指示子版本号

z：指示编译号

此外，函数还将该信息置于进入字符串 pszString 中。 在设备上，此函数也可用于确定 BREW 软件正在哪个芯片组上运行。

原型：

uint32 GETAEEVERSION(byte * pszString, int nSize, uint16 wFlags)

参数：

pszString
指向缓冲区的指针，包含版本号的字符串将置于该缓冲区中。
nSize
pszString 缓冲区的大小（字节）。
wFlags
指定要获取的信息类型。
  • GAV_LATIN1
  • 单字节字符串
  • GAV_MSM： ìN ”N.N.N (ADSARM7)“ 形式
  • 除了编译号以外，pszString 还包含有关处理器（例如：ARM7）和编译设备 BREW 所使用的编译器 (ADS) 的信息。例如：2.0.0.9 (ADSARM7)，它表明库是由使用 ARM7 处理器的设备上的 ADS 编译器编译。 SDK 不支持此标记， 只有在 BREW 设备环境下才支持此标记。

返回值：

包含版本号的 32 位数字，组成如下：

  • 高字的高字节 - 主版本号
  • 高字的低字节 次版本号
  • 低字的高字节 - 子版本号
  • 低字的低字节 - 编译号

备注：

无

另请参阅：

无

返回函数列表

GETAPPINSTANCE()

说明：

此函数用于返回当前正在运行的小程序的 IApplet 实例。 它在所有的 BREW API 调用、回调和事件中均有效。

原型：

IApplet * GETAPPINSTANCE(void)

参数：

无

返回值：

返回指向当前正在执行的小程序的 IApplet 指针。

备注：

无

另请参阅：

无

返回函数列表

GETCHTYPE()

说明：

此函数用于返回宽字符的类型（数字、字母及其它）。

原型：

TChType GETCHTYPE(AECHAR ch)

参数：

ch
要确定其类型的字符。

返回值：

给定字符的类型，可能的类型如下：

SC_ALPHA

SC_DIGIT

SC_WHITESPACE

SC_UNKNOWN

备注：

无

另请参阅：

TChType

返回函数列表

GETJULIANDATE()

说明：

此函数用于根据输入的秒值填充 JulianType 数据结构。 该值表示从 1980 年 1 月 6 日 00:00:00 GMT（设备参考时间）起至今的秒数。 如果输入值为 0（零），则返回当前的系统时间。

原型：

void GETJULIANDATE(uint32 dwSecs, JulianType * pDate)

参数：

dwSecs | 1980 年 1 月 6 日 GMT（设备参考时间）至今经过的秒数。
pDate | 指向返回时需要填充的结构的指针。

返回值：

无

备注：

在 Windows 上，dwSecs 的上限是设备参考时间 1980 年 1 月 6 日 00:00:00 GMT 和 PC 参考时间 1970 年 1 月 1 日 00:00:00 的差与 uint32 允许的最大值之间的差额。

另请参阅：

JulianType

GETTIMESECONDS()

GETTIMEMS()

GETUPTIMEMS()

返回函数列表

GETRAND()

说明：

此函数使用设备的随机数发生器，向输入缓冲区填充随机值数组。

原型：

void GetRand(byte * pDest, int nSize)

参数：

pDest | 指向目标缓冲区的指针。
nSize | 缓冲区的大小（字节）。

返回值：

无

备注：

此函数使用设备的随机数发生器，向输入缓冲区填充一系列随机字节。 该序列会在当前时间形成种子值，所以，除非间隔至少几毫秒，否则多次调用会得到相同的结果。 要获得最佳结果，可在每次调用事件处理函数时调用一次该函数。

另请参阅：

无

返回函数列表

GETTIMEMS()

说明：

此函数用于返回当前时间（毫秒）。 该调用的返回值取决于设备的当前时间值。
在设备上，该值从基站获取，在设备首次获取系统覆盖范围时该值可能有较大的
变化。

原型：

uint32 GETTIMEMS()

参数：

无

返回值：

从午夜开始经过的时间（毫秒数）。

备注：

无

另请参阅：

GETJULIANDATE()

GETTIMESECONDS()

GETUPTIMEMS()

返回函数列表

GETTIMESECONDS()

说明：

此函数用于返回从 1980 年 1 月 6 日 00:00:00 GMT 至今的秒数（已调整为当地时间）。

原型：

uint32 GETTIMESECONDS()

参数：

无

返回值：

1980 年 1 月 6 日 00:00:00 GMT 至今经过的时间。

备注：

无

另请参阅：

GETTIMEMS()

GETUPTIMEMS()

返回函数列表

GETTLS

说明：

获取指向 BREW 中 TLS 记录的预定义静态指针的便捷宏

原型：

void GETTLS(void *pToSet)

参数：

pToSet
填入 pToSet 的宏

返回值：

无

备注：

无

副作用：

填写 pToSet

另请参阅：

SETTLS

SETSTACKBOTTOM

SETSTATICPTR

返回函数列表

GETUPTIMEMS()

说明：

此函数用于返回设备开机后经过的时间（毫秒）。 它与 GETTIMEMS() 不同，其返回值不会因初次获取系统覆盖范围而发生较大的变化。

原型：

uint32 GETUPTIMEMS()

参数：

无

返回值：

设备开机后经过的时间（毫秒数）。

备注：

在 Emulator 上，此函数返回 Emulator 选择当前设备配置后经过的时间（毫秒数）。

另请参阅：

GETTIMEMS()

GETTIMESECONDS()

GETJULIANDATE()

返回函数列表

HTOLEL()

说明：

此函数用于将传递的无符号长整型值从主机字节顺序转换为网络字节顺序。

原型：

unsigned long HTOLEL(unsigned long ul)

参数：

ul
要转换的无符号长整型输入参数。

返回值：

转换值。

备注：

如果平台为低位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

HTOLES()

说明：

此函数用于将传递的无符号长整型值从网络字节顺序转换为主机字节顺序。

原型：

unsigned short HTOLES(unsigned short us)

参数：

us
要转换的无符号短整型输入参数。

返回值：

转换值。

备注：

如果平台为低位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

HTONL()

说明：

此函数用于将无符号长整型值从主机转换为网络字节顺序。

原型：

unsigned long HTONL(unsigned long ul)

参数：

ul
要转换的无符号长整型输入参数。

返回值：

转换值。

备注：

如果平台为高位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

HTONS()

说明：

此函数用于将无符号短整型值从主机转换为网络字节顺序。

原型：

unsigned short HTONS(unsigned short us)

参数：

us
要转换的无符号短整型输入参数。

返回值：

转换值。

备注：

如果平台为高位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

INET_ATON()

说明：

此函数用于将字符串转换为 InetAddr（无符号长整型）。

原型：

boolean INET_ATON(const char * psz, unsigned long * pulAddr)

参数：

psz | 包含地址的字符串（如 1.2.3.4）。
pulAddr | 指向要填充的 inet 地址的指针。

返回值：

如果已解析地址，则返回 TRUE。

否则，返回 FALSE。

备注：

INET_ATON 接受 '\0'、':'、'/' 和 ',' 作为字符串终结符，它们是常用的 URL 主机名分隔符。 因此，下列传递给 INET_ATON() 的字符串全都有效：

"1.2.3.4"

"1.2.3.4:80"

"1.2.3.4/hi"

"1.2.3.4,1.2.3.5"

所有字符串都将返回相同的 ulAddr，即 1.2.3.4

应答使用网络字节顺序，因此可以直接用于网络 API。

另请参阅：

无

返回函数列表

INET_NTOA()

说明：

此函数用于将 InetAdd（无符号长整型）转换为 ASCII 字符串。

原型：

void INET_NTOA(unsigned long ulAddr, char * pc, size_t nLen)

参数：

ulAddr | 要转换的 Iinet 地址。
pc | 写缓冲区。
nLen | pc 的大小。

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

JULIANTOSECONDS()

说明：

此函数用于返回从 CDMA 参考时间开始到指定的儒略日期时间所经过的秒数。

原型：

uint32 JULIANTOSECONDS(JulianType* pDate)

参数：

pDate
指向儒略日期时间结构 JulianType 的指针。

返回值：

从 CDMA 参考时间开始到指定的儒略日期时间所经过的秒数。

备注：

无

另请参阅：

GET_JULIANDATE()

JulianType

返回函数列表

LETOHL()

说明：

此函数用于将传递的无符号值从低位优先转换为主机字节顺序。

原型：

unsigned long LETOHL(unsigned long ul)

参数：

ul
要转换的无符号长整型输入参数。

返回值：

转换值。

备注：

如果平台为低位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

LETOHS()

说明：

此函数用于将传递的无符号短整型值从低位优先转换为主机字节顺序。

原型：

unsigned short LETOHS(unsigned short us)

参数：

us
要转换的无符号短整型输入参数。

返回值：

转换值

备注：

如果平台为低位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

LOCALTIMEOFFSET()

说明：

此函数用于返回相对于 UTC 的本地时区偏移量（以秒为单位）。 返回的可选标记用于指示是否已激活夏令制时间（如果是的话，则本地时区偏移值已考虑了偏移，标记仅用于控制时区名称的显示）。 将返回值与 UTC 相加即可得出本地时间，或者从本地时间减去返回值即可得出 UTC 时间。 UTC = 本地时间 - 偏移量（本函数的返回值）。

原型：

int32 LOCALTIMEOFFSET(boolean * pbDaylightSavings)

参数：

pbDaylightSavings
[in/out]
如果输入时不为 NULL，则返回时该标记将指示是否已激活夏时制时间

返回值：

相对于 UTC 的本地时区偏移量（秒）。

备注：

无

另请参阅：

无

返回函数列表

LOCKMEM()

说明：

警告：如果没有透彻理解与基于句柄处理的内存相关的全部规则，请勿使用此函数。 默认情况下，通过 BREW 堆分配的所有内存均已锁定，不能重新分配。 此函数为调用程序提供了一种方法，以指定最近分配和解锁的块现已锁定且不能移动。

初始分配：

pme->m_ptr = MALLOC(100);
UNLOCKMEM(&pme->m_ptr);

使用：

LOCKMEM(&pme->m_ptr);

执行工作...

UNLOCKMEM(&pme->m_ptr);

如上所述，此函数接受指向已分配内存句柄的指针。 然后，该函数将内存中的块标记为固定。

原型：

void LOCKMEM(void ** ppHandle);

参数：

无

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

MAKE_RGB()

说明：

此函数用于返回指定红、绿和蓝色的 RGBVAL。

原型：

RGBVAL MAKE_RGB(uint32 r, uint32 g, uint32 b)

参数：

r | 红色值
g | 绿色值
b | 蓝色值

返回值：

RGBVAL

备注：

不验证指定值。

另请参阅：

RGBVAL

返回函数列表

MALLOC()

说明：

此函数对应于标准 C 库中的 malloc()， 它将返回的内存全部置零。

原型：

void * MALLOC(DWORD dwSize)

参数

dwSize
缓冲区大小（字节）。

返回值：

指向已分配内存的指针。

备注：

无

另请参阅：

FREE()

REALLOC()

返回函数列表

MALLOCREC()

说明：

此函数是 MALLOC() 的别名，有助于防止类型转换， 它将返回的内存全部置零。

原型：

void * MALLOCREC(type)

参数：

type
C 类型定义，适于转换和获取 sizeof()。

返回值：

如果成功，则返回有效指针，指向大小为 sizeof(type) 字节的缓冲区。

如果函数失败，则返回 NULL。

备注：

以下是其用法。 要实现以下操作：

pMe = (struct MeStruct *)MALLOC(sizeof(struct MeStruct));

您可以使用：

pMe = MALLOCREC(MeStruct);

通过在使用 sizeof 的位置放置（不安全）转换，可以避免出现如下错误：

pMe = (struct MeStruct *)MALLOC(sizeof(struct TypoStruct));

类似错误可能导致超标分配或无效分配（具体取决于 sizeof TypoStruct）。

另外，它还更加简练。

另请参阅：

MALLOC()

返回函数列表

MALLOCREC_EX()

说明：

此函数是 MALLOC() 的别名，有助于避免类型转换，并可获取额外内存，从而避免多个堆节点。它将返回的内存全部置零。

原型：

void * MALLOCREC_EX(type, size)

参数：

type | C 类型定义，适于转换和获取 sizeof()。
size | 额外字节数。

返回值：

如果成功，则返回有效指针，指向大小为 sizeof(type) +size 字节的缓冲区。

如果函数失败，则返回 NULL。

备注：

以下是其用法。 假设有以下结构：

typedef struct NVPair
{
char * pszName;
char * pszValue;
} NVPair;

和以下创建函数：

NVPair * NVPair_New(const char * pszName, const char * pszValue);

您可以使用以下代码：

NVPair * NVPair_New(const char * cpszName, const char * cpszValue)
{
NVPair * me;
me = MALLOCREC(NVPair);
if (me) {
me->pszName = STRDUP(cpszName);
if (me->pszName) {
me->pszValue = STRDUP(cpszValue);
if (me->pszValue) {
return me; // 成功！
}
FREE(me->pszName);
}
FREE(me);
}
return 0;
}

或者使用：

NVPair * NVPair_New(const char * cpszName, const char * cpszValue)
{
NVPair * me;
me = MALLOCREC_EX(NVPair, STRLEN(cpszName) +STRLEN(cpszValue) +2);
if (me)
{
me->pszName = (char *)(me +1);
STRCPY(me->pszName,cpszName);
me->pszValue = me->pszName +STRLEN(me->pszName) +1;
STRCPY(me->pszValue,cpszValue);
}
return me;
}

前者使用了 3 个堆节点，而后者仅使用 1 个。此外还简化了释放操作，下面是一个简单的例子：

NVPair_Delete(NVPair * me)
{
FREE(me->pszValue);
FREE(me->pszName);
FREE(me);
}

而使用 MALLOCREC_EX 则为：

NVPair_Delete(NVPair * me)
{
FREE(me);
}

另请参阅：

MALLOCREC()

返回函数列表

MEMCHR()

说明：

此函数是标准 C 库提供的 memchr() 函数的包装， 其行为与 memchr() 相同。 它用于在内存缓冲区中查找字符。

原型：

char * MEMCHR(const void * buf, int c, size_t length)

参数：

buf | 要搜索的内存。
c | 要定位的字符。
length | buf 的大小。

返回值：

指向 buf 中出现的第一个 c 的指针。

如果找不到 c，则返回 NULL。

备注：

无

另请参阅：

STRCHR()

返回函数列表

MEMCHREND()

说明：

此函数用于在内存缓冲区中查找字符，或返回指向缓冲区末尾的指针。

原型：

char * MEMCHREND(const char * buf, int c, size_t length)

参数：

buf | 要搜索的内存。
c | 要定位的字符。
length | buf 的大小。

返回值：

指向 buf 中出现的第一个 c 的指针。

如果找不到 c，则返回指向 buf + length 的指针。

备注：

无

另请参阅：

MEMCHR()

STRCHREND()

返回函数列表

MEMCMP()

说明：

此函数是标准 C 库提供的 memcmp() 函数的包装， 其行为与 memcmp() 相同。 它用于比较 p1 和 p2 的 count 个字节。

原型：

int MEMCMP(const void * p1, const void * p2, size_t count)

参数：

p1, p2 | 指向要比较的内存缓冲区的指针。
count | 要比较的字节数。

返回值：

如果两个缓冲区包含相同的 count 个字节，则返回 0（零）。

如果 p1 的第一个不同字节小于 p2 的对应字节，则返回值 < 0。

如果 p1 的第一个不同字节大于 p2 的对应字节，则返回值 > 0。

备注：

无

另请参阅：

无

返回函数列表

MEMCPY()

说明：

此函数是标准 C 库提供的 memcpy() 函数的包装， 其行为与 memcpy() 相同。 它用于将 src 中的 count 个字节复制到 dest 中。

原型：

void * MEMCPY(void * dest, const void * src, uint16 count)

参数：

dest | 指向目标缓冲区的指针。
src | 指向源缓冲区的指针。
count | 必须从 src 复制到 dest 的字节数。

返回值：

如果成功，则返回指向 dest 缓冲区的指针。

备注：

无

另请参阅：

MEMSET()

返回函数列表

MEMMOVE()

说明：

此函数是标准 C 库提供的 memmove() 函数的包装， 其行为与 memmove() 相同。 它用于将 src 中的 count 个字节复制到 dest 中。

原型：

void * MEMMOVE(void * dest, const void * src, size_t count)

参数：

dest | 指向目标缓冲区的指针
src | 指向源缓冲区的指针
count | 必须从 src 复制到 dest 的字节数。

返回值：

指向 dest 缓冲区的指针。

备注：

无

另请参阅：

MEMSET()

返回函数列表

MEMRCHR()

说明：

此函数用于在缓冲区中查找某个字符最后一次出现的位置。

原型：

char * MEMRCHR(const char * buf, char c, int length)

参数：

buf | 要搜索的内存。
c | 要定位的字符。
length | buf 的大小。

返回值：

指向 buf 中最后一次出现的 c 的指针。

如果找不到 c，则返回 NULL。

备注：

无

另请参阅：

MEMCHR()

STRRCHR()

返回函数列表

MEMRCHRBEGIN()

说明：

此函数用于在内存缓冲区中查找某个字符最后一次出现的位置，或返回指向缓冲区开始处的指针。

原型：

char * MEMRCHRBEGIN(const char * buf, char c, int length)

参数：

buf | 要搜索的内存。
c | 要定位的字符。
length | buf 的大小。

返回值：

指向 buf 中最后一次出现的 c 的指针。

如果找不到 c，则返回指向 buf 的指针。

备注：

无

另请参阅：

MEMRCHR()

MEMCHREND()

返回函数列表

MEMSET()

说明：

此函数是标准 C 库提供的 memset() 函数的包装， 其行为与 memset() 相同。 它用于将 dest 缓冲区的前 count 个字节设置为指定字节 b。

原型：

void * MEMSET(void * dest, int b, size_t count)

参数：

dest | 指向目标缓冲区的指针。
b | 指定必须复制到 dest 缓冲区的字节。
count | 指定 dest 中必须设为值 b 的字节数。

返回值：

如果成功，则返回指向目标缓冲区的指针。

备注：

无

另请参阅：

MEMCPY()

返回函数列表

MEMSTR()

说明：

此函数用于在内存缓冲区中查找某字符串第一次出现的位置。

原型：

char * MEMSTR(const char * buf, const char * psz, int length)

参数：

buf | 要搜索的内存。
psz | 要定位的字符串。
length | buf 的大小。

返回值：

指向 buf 中出现的第一个 psz 的指针。

如果找不到 psz，则返回 NULL。

备注：

无

另请参阅：

STRSTR()

返回函数列表

NTOHL()

说明：

此函数用于将传递的无符号长整型值从网络字节顺序转换为主机字节顺序。

原型：

unsigned long NTOHL(unsigned long ul)

参数：

ul
要转换的输入参数。

返回值：

转换值。

备注：

如果平台为高位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

NTOHS()

说明：

此函数用于将传递的无符号短整型值从网络转换为主机字节顺序。

原型：

unsigned short us NTOHS(unsigned short us)

参数：

us
要转换的输入参数。

返回值：

转换值。

备注：

如果平台为高位优先，则函数将返回未转换的输入参数。

另请参阅：

无

返回函数列表

OEMSTRLEN()

说明：

此函数用于返回字节字符串的长度。 该字符串必须以 NULL 结尾。 如果字符的首字节大于 0x7f，则将其作为双字节字符处理， 这两个字节将计为一个单字符。

原型：

int OEMSTRLEN(const byte * p)

参数：

p
指向以 NULL 结尾的字节字符串的有效指针

返回值：

如果成功，则返回字节字符串的长度

如果 p 为 NULL，则返回 0（零）

备注：

无

另请参阅：

无

返回函数列表

OEMSTRSIZE()

说明：

此函数用于返回字节字符串的大小（字节）。 输入值必须以 NULL 结尾。

原型：

int OEMSTRSIZE(const byte * p)

参数：

p
指向以 NULL 结尾的字节字符串的指针

返回值：

如果成功，则返回字节字符串的大小（字节）

如果 p 为 NULL，则返回 0（零）

备注：

如果成功，则返回字符串的大小（字节），包括 NULL 终结符（除非字符串为空，
则返回 0）。

例如：

OEMSTRSIZE("") == 0（空字符串）

OEMSTRSIZE("h") == 2 ('h' +'\0')

另请参阅：

无

返回函数列表

REALLOC()

说明：

此函数对应于标准 C 库中的 realloc()。

原型：

void * REALLOC(void * pSrc, uint32 dwSize)

参数：

pSrc | 指向先前已分配的内存
dwSize | 新的大小（字节）

返回值：

指向新分配内存的指针。

备注：

无

另请参阅：

MALLOC()

FREE()

返回函数列表

SETAEERECT()

说明：

此函数用于通过起点、宽度和高度初始化指定的矩形。

原型：

void SETAEERECT(AEERect * rc, int x, int y, int cx, int cy)

参数：

rc | 要初始化的矩形
x | 矩形起点的 X 坐标
y | 矩形起点的 Y 坐标
cx | 宽度
cy | 高度

返回值：

无

备注：

不验证指定值。 如果是 NULL 矩形，将导致失效。

另请参阅：

AEERect

返回函数列表

SETSTACKBOTTOM

说明：

此函数用于设置指向 BREW 栈底的预定义静态指针，并返回原值

原型：

void *SETSTACKBOTTOM(void *pNew)

参数：

pNew
新值

返回值：

原值

备注：

使用时请注意，只有线程包或系统级代码才需要调用此函数

副作用：

BREW 使用此值检验堆栈下溢

另请参阅：

SETTLS

GETTLS

SETSTATICPTR

返回函数列表

SETSTATICPTR

说明：

此函数用于设置 BREW 中的预定义静态指针，并返回原值

原型：

void *SETSTATICPTR(int nSPId, void *pNew)

参数：

nSPId | 以下静态指针 ID 之一：
 | AEESPID_STACKBOTTOM | 当前堆栈栈底。由于 BREW 在内部使用此值检查堆栈，因此要小心使用。 *只有*在执行线程包，要求 BREW 允许使用堆栈时才可设置该值
 | AEESPID_TLS | 指向线程“本地”数据的指针。该值必须在当前堆栈上。由于 BREW 还将它作为“栈顶”检验堆栈，所以调用任何 BREW API 时，该值将大于 SP。
pNew | 新值

返回值：

原值

备注：

仅支持预定义的 id，使用其它值调用此函数将产生异常。

因此请小心使用。

副作用：

BREW 使用 AEESPID_STACKBOTTOM 和 AEESPID_TLS 检查堆栈。 因此，通常只有用户线程包或 BREW 系统代码才能使用这些 Id 调用 setstaticptr。

另请参阅：

SETTLS

SETSTACKBOTTOM

GETTLS

返回函数列表

SETTLS

说明：

此函数用于设置指向 BREW 中 TLS 记录的预定义静态指针，并返回原值

原型：

void *SETSTLS(void *pNew)

参数：

pNew
新值

返回值：

原值

备注：

使用时请注意，只有线程包或系统级代码才需要调用此函数

副作用：

BREW 使用此值检查堆栈溢出，任何调用 SETTLS() 的函数在返回前均应调用 SETTLS() 恢复栈顶

另请参阅：

GETTLS

SETSTACKBOTTOM

SETSTATICPTR

返回函数列表

SPRINTF()

说明：

此函数是标准 C 库提供的 sprintf() 函数的包装， 其行为与 sprintf() 相同。 它用于将格式化数据写入字符串。 此函数始终使用单字节字符串作为输入。 要处理包含 AECHAR 的字符串，请使用 WSPRINTF()。此函数不支持格式字符串中的 %f。 如果在格式字符串中出现 %f，则函数将返回 0，不做任何处理。

原型：

int SPRINTF( char *buffer, const char *format [, argument] ... );

参数：

buffer | 输出的保存位置
format | 格式控制字符串
argument | 可选参数。 有关该函数及其参数的详细信息，请参考相应平台 (Windows / ARM) 上标准 C 库函数 sprintf() 的文档资料

返回值：

返回保存在缓冲区中的字节数，不计结尾的 null 字符。

备注：

无

另请参阅：

DBGPRINTF()

VSPRINTF()

VSNPRINTF()

WSPRINTF()

返回函数列表

STR_TO_WSTR()

注意：建议不使用此函数， 而使用 STRTOWSTR()。

说明：

此函数用于将单字节字符串转换为宽字符串。

原型：

AECHAR * STR_TO_WSTR(const char * pszIn, AECHAR * pDest, int nSize)

参数：

pszIn | 指向由单字节字符组成、以 NULL 结尾的字符串的指针
pDest | 指向接收宽字符串的目标缓冲区的指针
nSize | pDest 缓冲区的大小（字节）。 如果 nSize == 0，则函数不进行任何转换， 并原样返回 pDest，不作任何更改。

返回值：

如果成功，则返回目标字符串。

备注：

无

另请参阅：

WSTR_TO_STR()

返回函数列表

STRBEGINS()

说明：

此函数用于判断字符串是否以某前缀开始。

原型：

boolean STRBEGINS(const char * pszPrefix, const char * psz)

参数：

pszPrefix | 要检验的前缀。
psz | 要判断的字符串。

返回值：

如果 psz 是以 pszPrefix 开始，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

STRCAT()

说明：

此函数是标准 C 库提供的 strcat() 函数的包装， 其行为与 strcat() 相同。 它用于将
src 字符串添加到 dest，并返回 dest 字符串。 src 中直至第一个 NULL 之前的所有字符（包括 NULL 字符）都将添加至 dest。 此函数始终使用单字节字符串作为输入。 应用程序若要添加宽字符串，则必须使用 WSTRCAT() 函数。

原型：

char * STRCAT(char * dest, const char * src)

参数：

dest | 指向以 NULL 结尾的目标字符串的指针。
src | 指向以 NULL 结尾的源字符串的指针。

返回值：

如果成功，则返回目标字符串。

备注：

无

另请参阅：

WSTRCAT()

返回函数列表

STRCHR()

说明：

此函数是标准 C 库提供的 strchr() 函数的包装， 其行为与 strchr() 相同。 它用于在字符串中查找字符。 该函数始终使用单字节字符作为输入。

原型：

char * STRCHR(const char * string, int c)

参数：

string | 要搜索的以 NULL 结尾的字符串。
c | 要定位的字符。

返回值：

指向 string 中出现的第一个 c 的指针。

如果找不到 c，则返回 NULL。

备注：

无

另请参阅：

WSTRCHR()

返回函数列表

STRCHREND()

说明：

此函数用于在字符串中查找字符的首次出现，如果找不到，将返回指向字符串结尾的指针。

原型：

char * STRCHREND(const char * string, char c)

参数：

string | 要搜索的以 NULL 结尾的字符串。
c | 要定位的字符。

返回值：

指向字符串中出现的第一个 c 的指针。

如果找不到 c，则返回指向字符串结尾 ('\0') 的指针。

备注：

无

另请参阅：

STRCHR()

返回函数列表

STRCHRSEND()

说明：

此函数用于在字符串中查找某串字符的首次出现，如果找不到，将返回指向字符串结尾的指针。

原型：

char * STRCHRSEND(const char * string, const char * pszChars)

参数：

string | 要搜索的以 NULL 结尾的字符串。
pszChars | 要查找的以 Null 结尾的字符串。

返回值：

指向字符串中出现的第一个 pszChars 的指针。

如果找不到，则返回指向字符串结尾 ('\0') 的指针。

备注：

无

另请参阅：

STRCHREND()

返回函数列表

STRCMP()

说明：

此函数是标准 C 库提供的 strcmp() 函数的包装， 其行为与 strcmp() 相同。 它用于比较两个给定的单字节字符串。 此函数始终使用单字节字符作为输入。

原型：

int STRCMP(const char * str1, const char * str2)

参数：

str1,str2
指向需要比较的两个以 NULL 结尾的字符串的指针。

返回值：

如果 string1 小于 string2，则返回值 < 0。

如果 string1 等于 string2，则返回 0（零）。

如果 string1 大于 string2，则返回值 > 0。

备注：

无

另请参阅：

WSTRCMP()

返回函数列表

STRCPY()

说明：

此函数是标准 C 库提供的 strcpy() 函数的包装， 其行为与 strcpy() 相同。 它用于将
src 字符串复制到 dest 并返回 dest 字符串。 src 中直至第一个 NULL 之前的所有字符（包括第一个 NULL 字符）都将复制到 dest 中。 此函数始终使用单字节字符串作为输入。 如果应用程序要将某个缓冲区中的宽字符串复制到其它缓冲区，则必须使用 WSTRCPY() 函数。

原型：

char * STRCPY(char * dest, const char * src)

参数：

dest | 指向目标字符串的指针。
src | 指向源字符串的指针。

返回值：

如果成功，则返回指向目标字符串的指针。

备注：

无

另请参阅：

WSTRCPY()

WSTRNCOPYN()

返回函数列表

STRDUP()

说明：

此函数是标准 C 库提供的 strdup() 函数的包装， 其行为与 strdup() 相同，但返回的内存必须使用 FREE() 释放。它用于分配内存并复制和返回字符串。 此函数始终使用单字节字符作为输入。 如果应用程序要将缓冲区中的双字节字符 AECHAR 复制到其它缓冲区，则必须始终使用 WSTRDUP()。

原型：

char * STRDUP(const char * string)

参数：

string
要复制的字符串。

返回值：

指向新复制字符串的指针。

如果函数失败，则返回 NULL。

备注：

无

另请参阅：

FREE()

MALLOC()

返回函数列表

STRENDS()

说明：

此函数用于判断字符串是否以某后缀结尾。

原型：

boolean STRENDS(const char * pszSuffix, const char * psz)

参数：

pszSuffix | 要检验的后缀。
psz | 要判断的字符串。

返回值：

如果 psz 是以 pszSuffix 结尾，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

无

返回函数列表

STREXPAND()

说明：

此函数用于将输入字符串扩展为宽字符。 如果字符小于或等于 127，则将加倍其宽度。 如果大于 127，则将其复制到 pDest 中。

原型：

void STREXPAND
(
const byte * pSrc,
int nCount,
AECHAR * pDest,
int nSize
)

参数：

pSrc | 以 NULL 结尾的源字符串。
nLen | 源字符串的长度（以字符为单位）。
pDest | 指向目标缓冲区的指针。
nSize | 目标缓冲区的大小（字节）。

返回值：

无

备注：

无

另请参阅：

WSTRCOMPRESS()

返回函数列表

STRICMP()

说明：

此函数是标准 C 库提供的 strcasecmp()、stricmp() 或 strcmpi() 函数的包装， 其行为与 strnicmp() 相同。 它用于比较 str1 和 str2（区分大小写）。

原型：

int STRICMP(const char * str1, const char * str2)

参数：

str1,str2
指向要比较的两个以 NULL 结尾的字符串的指针。

返回值：

如果 string1 小于 string2，则返回值 < 0。

如果 string1 等于 string2，则返回 0（零）。

如果 string1 大于 string2，则返回值 > 0。

备注：

无

另请参阅：

STRCMP()

返回函数列表

STRISTR()

说明：

此函数用于在一个字符串中查找首次出现的另一个字符串。 该查找区分大小写。

原型：

char * STRISTR(const char * pszHaystack, const char * pszNeedle)

参数：

pszHaystack | 在其中进行搜索的字符串。
pszNeedle | 要查找的字符串。

返回值：

指向 pszHaystack 中出现的第一个 pszNeedle 的指针。

如果找不到 pszNeedle，则返回 NULL。

备注：

无

另请参阅：

STRSTR()

返回函数列表

STRLCAT()

说明：

此函数用于将字符串连接到目标缓冲区，并确保它以 NULL 结尾。

原型：

size_t STRLCAT(char * dst, const char * src, size_t nSize);

参数：

dst： 目标字符串。 要连接到的字符串。

src： 源字符串。 要复制的字符串。

nSize： 目标缓冲区大小（字节）。

返回值：

作为连接结果而尝试创建的整个字符串的长度。

如果出现错误，则返回 (size_t)-1。

备注：

要查看是否发生截断，可以对比目标缓冲区的长度，检查返回值。

另请参阅：

STRCAT()

返回函数列表

STRLCPY()

说明：

此函数用于将字符串复制到目标缓冲区中，并确保它以 NULL 结尾。

原型：

size_t STRLCPY(char * dst, const char * src, size_t nSize);

参数：

dst | 目标字符串。 要复制到的字符串。
src | 源字符串。 要复制的字符串。
nSize | 目标缓冲区大小（字节）。

返回值：

尝试复制的整个字符串的长度。

如果出现错误，则返回-1。

备注：

要查看是否发生截断，可以对比目标缓冲区的长度，检查返回值。

另请参阅：

STRCPY()

STRNCPY()

返回函数列表

STRLEN()

说明：

此函数是标准 C 库提供的 strlen() 函数的包装， 其行为与 strlen() 相同。 它用于获取以 NULL 结尾的给定字符串的长度。 该函数始终使用单字节字符作为输入。 若要获取宽字符串的长度，请使用 WSTRLEN()。

原型：

int STRLEN(const char * str)

参数：

str
以 NULL 结尾，要确定其长度的字符串。

返回值：

字符串中的字符数，不包括结尾的 NULL。

备注：

无

另请参阅：

WSTRLEN()

返回函数列表

STRLOWER()

说明：

此函数用于将单字节字符串全部改为小写。

原型：

char * STRLOWER(char * psz)

参数：

psz
要改为小写的字符串。

返回值：

psz

备注：

无

另请参阅：

STRUPPER()

返回函数列表

STRNCMP()

说明：

此函数是标准 C 库提供的 strcmp() 函数的包装， 其行为与 strncmp() 相同。 它用于对两个给定单字节字符串中至多 length 个字节进行比较。

原型：

int STRNCMP(const char * str1, const char * str2, size_t length)

参数：

str1,str2 | 指向要比较的两个以 NULL 结尾的字符串的指针。
length | 要比较的最大字节数。

返回值：

如果 string1 小于 string2，则返回值 < 0。

如果 string1 等于 string2，则返回 0（零）。

如果 string1 大于 string2，则返回值 > 0。

备注：

无

另请参阅：

STRCMP()

WSTRNCMP()

返回函数列表

STRNCPY()

说明：

此函数是标准 C 库函数 strncpy() 的包装。 它将某个字符串中指定数目的字符复制到其它字符串。 strncpy() 函数用于将 strSource 中前 count 个字符复制到 strDest 中，并返回 strDest。 如果 count 小于或等于 strSource 的长度，则不向复制的字符串添加 NULL 字符。 如果 count 大于 strSource 的长度，则将使用 NULL 字符填充目标字符串，
直至其长度达到 count。 如果源和目标字符串重叠，则 strncpy 的行为不确定。

原型：

char * STRNCPY(char * strDest, const char * strSource, size_t count)

参数：

strDest | [in/out] | 目标字符串。
strSource | [in/out] | 源字符串。
count | [in] | 要复制的字符数。

返回值：

strDest

备注

无

另请参阅：

无

返回函数列表

STRNICMP()

说明：

此函数是标准 C 语言库提供的 strncasecmp ()、strnicmp () 或 strncmpi () 函数的包装， 其行为与 strnicmp() 相同。 它用于对 str1 和 str2 中至多 length 个字节进行比较
（区分大小写）。

原型：

int STRNICMP(const char * str1, const char * str2, size_t length)

参数：

str1,str2 | 指向要比较的两个以 NULL 结尾的字符串的指针。
length | 要比较的最大字节数。

返回值：

如果 string1 小于 string2，则返回值 < 0。

如果 string1 等于 string2，则返回 0（零）。

如果 string1 大于 string2，则返回值 > 0。

备注：

无

另请参阅：

STRICMP()

WSTRNCMP()

返回函数列表

STRRCHR()

说明：

此函数是标准 C 库提供的 strrchr() 函数的包装， 其行为与 strrchr() 相同。 它用于在字符串中搜索字符的最后一次出现。 该函数始终使用单字节字符串作为输入。

原型：

char * STRRCHR(const char * string, int c)

参数：

string | 要搜索的以 NULL 结尾的字符串。
c | 要定位的字符。

返回值：

如果找到，则返回指向字符串中最后一次出现的 c 的指针。

如果找不到 c，则返回 NULL。

备注：

无

另请参阅：

WSTRRCHR()

返回函数列表

STRSTR()

说明：

此函数用于在一个字符串中查找首次出现的另一个字符串。 此函数是标准 C 库提供的 strstr () 函数的包装， 其行为与 strstr() 相同。 此函数可在一个字符串中查找另一字符串， 并始终使用单字节字符作为输入。

原型：

char * STRSTR(const char * pszHaystack, const char * pszNeedle)

参数：

pszHaystack | 在其中进行搜索的字符串
pszNeedle | 要查找的字符串

返回值：

指向 pszHaystack 中出现的第一个 pszNeedle 的指针。

如果找不到 pszNeedle，则返回 NULL。

备注：

无

另请参阅：

STRCHR()

MEMSTR()

返回函数列表

STRTOUL()

说明：

此函数是标准 C 库中 strtoul() 函数的包装， 用于将字符串转换为无符号长整型值。
在其无法识别为一个数字部分的第一个字符处，函数将停止读取字符串 nptr。 无法识别的字符可能是结尾的 NULL 字符，也可能是大于或等于基数的第一个数字字符。 如果 endptr 不为 NULL，中止扫描的字符指针将保存在 endptr 所指的位置。 如果无法执行转换（找不到有效的数字或指定的基数无效），则 nptr 的值也将保存在 endptr 所指的位置。

原型：

unsigned long STRTOUL(const char * nptr, char * * endptr, int base)

参数：

nptr | [in] | 要转换的以 NULL 结尾的字符串。
endptr | [out] | 如果输入时不为 NULL，则返回时将指向中止扫描的字符。
base | [in] | 要使用的数字基数。

返回值：

转换值

如果无法执行转换，则返回 0（零）。

备注：

无

另请参阅：

无

返回函数列表

STRTOWSTR()

说明：

此函数用于将单字节字符串转换为宽字符串。

原型：

AECHAR * STRTOWSTR(const char * pszIn, AECHAR * pDest, int nSize)

参数：

pszIn | 指向由单字节字符组成、以 NULL 结尾的字符串的指针。
pDest | 指向接收宽字符串的目标缓冲区的指针。
nSize | pDest strSource缓冲区的大小（字节）。 如果 nSize == 0，则函数不进行任何转换， 并原样返回 pDest，不作任何更改。 nSize 为负值则无效。

返回值：

如果成功，则返回目标字符串。

副作用：

如果开发者指定的缓冲区长度小于 26 字节，则将从右侧裁剪结果。

备注：

无

另请参阅：

WSTRTOSTR()

返回函数列表

STRUPPER()

说明：

此函数用于将单字节字符串全部改为大写。

原型：

char * STRUPPER(char * psz)

参数：

psz
要改为大写的字符串。

返回值：

psz

备注：

无

另请参阅：

STRLOWER()

返回函数列表

SYSFREE()

说明：

此函数使开发者可以返回从 CONVERTBMP() 中返回的系统内存指针。 该函数仅对 CONVERTBMP() 返回的内存对象有效，其中已将 bReallocated 标记设为 TRUE。

原型：

void SYSFREE(void * pBuff)

参数：

pBuff
指向 CONVERTBMP() 分配的内存的指针。

返回值：

无

备注：

无

另请参阅：

CONVERTBMP()

返回函数列表

UNLOCKMEM()

说明：

警告：如果没有透彻理解与基于句柄处理的内存相关的全部规则，请勿使用此函数。 默认情况下，通过 BREW 堆分配的所有内存均已锁定，不能重新分配。 此函数为调用者提供了一种方法，以指定可以移动最近分配的内存块。 调用方法如下：

初始分配：

pme->m_ptr = MALLOC(100);
UNLOCKMEM(&pme->m_ptr); // 使内存能够自由移动。

使用：

LOCKMEM(&pme->m_ptr);

执行工作...

UNLOCKMEM(&pme->m_ptr);

如上所述，此函数接受指向已分配内存句柄的指针。 然后，该函数将内存中的块标记为可移动。

注意：必须避免出现以下两种危险情况：

  • 传递驻留在可移动内存块中的内存的句柄。
  • 将句柄分配给已被其它块中句柄引用的内存。

原型：

void UNLOCKMEM(void ** ppHandle);

参数：

无

返回值：

无

备注：

无

另请参阅：

无

返回函数列表

UTF8_TO_WSTR()

注意：建议不使用此函数， 而使用 UTF8TOWSTR()。

说明：

此函数用于将 UTF8 字符串转换为宽字符串。

原型：

boolean UTF8_TO_WSTR
(
const byte * pSrc,
int nLen,
AECHAR * pDst,
int nSize
)

参数：

pSrc | 指向以 NULL 结尾的输入字符串的指针。
nLen | 输入字符串的长度（字节）。
pDst | 目标字符串。
nSize | 目标的大小（字节）。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

WSTR_TO_UTF8()

返回函数列表

UTF8TOWSTR()

说明：

此函数用于将 UTF8 字符串转换为宽字符串。

原型：

boolean UTF8TOWSTR
(
const byte * pSrc,
int nLen,
AECHAR * pDst,
int nSize
)

参数：

pSrc | 指向以 NULL 结尾的输入字符串的指针。
nLen | 输入字符串的长度（字节）。
pDst | 目标字符串。
nSize | 目标的大小（字节）。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

WSTRTOUTF8()

返回函数列表

VSNPRINTF()

说明：

此函数的功能与 VSPRINTF 相似， 用于将格式化输出写入流。 当前仅支持单字节缓冲流。 此函数可以将 AECHAR 或 AECHAR * 字符串作为输入（分别使用 %C 和 %S）， 但不支持格式字符串中的 %f。 如果在格式字符串中出现 %f，则函数将返回 -1，
不做任何处理。

原型：

int32 VSNPRINTF(char *buf, uint32 f, const char *format, va_list list);

参数：

buf | 写输出的位置。 可以为 NULL，以度量最终格式化字符串的空间。
f | 缓冲区的大小。 如果缓冲区为 NULL，则使用 0。 最大为 0x7FFFFFFF。 0x80000000 及其上保留用于标记。
format | 格式控制字符串
list | 可选参数列表

返回值：

写入输出的字符数（包括 NULL 终止符）。

如果缓冲区为 NULL 且 f 为 0，则函数不执行任何写操作，并返回最终格式化字符串的长度（包括 NULL 字符）。

如果出现错误或缓冲区大小不足以存储最终格式化的字符串，则返回值 -1。

备注：

无

另请参阅：

DBGPRINTF()

SPRINTF()

VSPRINTF()

WSPRINTF()

返回函数列表

VSPRINTF()

说明：

此函数是标准 C 库提供的 vsprintf() 函数的包装， 其行为与 vsprintf() 相同。 它用于将格式化数据写入字符串。 此函数始终使用单字节字符串作为输入。 它不支持格式字符串中的 %f。 如果在格式字符串中出现 %f，则函数将返回 0，不做任何处理。

原型：

int VSPRINTF(char * pszDest,const char * pszFormat,va_list arg);

参数：

pszDest： 输出的保存位置

pszFormat： 格式控制字符串

arg： 可选参数。 有关该函数及其参数的详细信息，请参考相应平台 (Windows / ARM) 上标准 C 库函数 sprintf() 的文档资料

返回值：

返回保存在缓冲区中的字节数，不计结尾的 null 字符。

备注：

无

另请参阅：

DBGPRINTF()

SPRINTF()

VSNPRINTF()

WSPRINTF()

返回函数列表

WEB_ERROR_MAP()

说明：

此函数用于将 WebRespInfo 错误映射到 AEEError.h 头文件。

原型：

WEB_ERROR_MAP(nCode)
(
  (
    (nCode) < 0
  ) ? -(nCode)
  :WEB_ERROR_SUCCEEDED
  (
    (nCode)
  ) ? SUCCESS
   :WEB_ERROR_PROTOCOL
  )
)

参数：

nCode
函数列表 中的错误代码。

备注：

此函数可以交换协议错误代码等信息，并有助于 API 直接向其客户端返回 AEE 错误。

另请参阅：

WebRespInfo

WEB_ERROR_SUCCEEDED()

返回函数列表

WEB_ERROR_SUCCEEDED()

说明：

此函数用于确定 WebRespInfo 错误代码是否表示“成功”。

原型：

WEB_ERROR_SUCCEEDED(nCode)(((nCode) >= 200) && ((nCode) < 300))

参数：

nCode
函数列表 中的错误代码。

返回值：

如果 nCode 为成功的错误值，则返回 TRUE。

否则，返回 FALSE。

备注：

无

另请参阅：

WebRespInfo

返回函数列表

WSPRINTF()

说明：

此函数对应于宽字符串的 sprintf()， 用于将格式化数据写入字符串。 与 sprintf() 相比，此函数有一定的限制。 它只能将字符串处理为 %s，而不能以“长度/格式指定符”
格式处理字符串。 该函数不支持格式字符串中的 %f。 如果在格式字符串内发现 %f，函数将在目标字符串的起始处填充一个 null 字符，并立即返回，不进行任何处理。

原型：

void WSPRINTF(AECHAR *pDest, int nSize, AECHAR *pFormat,...)

参数：

pDest | 输出的保存位置
nSize | 指定 pDest 缓冲区总的大小（字节）
pFormat | 格式控件字符串 有关该函数及其参数的详细信息，请参考相应平台 (Windows / ARM) 上标准 C 库函数 sprintf() 的文档资料

返回值：

无

备注：

无

另请参阅：

DBGPRINTF()

SPRINTF()

VSPRINTF()

VSNPRINTF()

返回函数列表

WSTR_TO_FLOAT()

注意：建议不使用此函数， 而使用 WSTRTOFLOAT()。

说明：

此函数用于将宽字符串转换为浮点值。 函数内部首先使用 WSTR_TO_STR() 将给定的宽字符串转换为单字节字符串，然后使用标准 C 库函数 atof() 将单字节字符串转换为双精度值。

原型：

double WSTR_TO_FLOAT(const AECHAR * psz)

参数：

psz
指向必须转换为浮点值的宽字符串（以 NULL 结尾）的指针。

返回值：

如果成功，则返回给定字符串的浮点值。

否则，返回 0.0。

备注：

无

另请参阅：

FLOAT_TO_WSTR()

返回函数列表

WSTR_TO_STR()

建议不使用此函数， 而使用 WSTRTOSTR()。

说明：

此函数用于将宽字符串转换为单字节字符串。

原型：

char * WSTR_TO_STR(const AECHAR * pIn, char * pszDest, int nSize)

参数：

pIn | 指向必须转换为单字节字符串的宽字符串（以 NULL 结尾）的指针。
pszDest | 指向接收单字节字符串的目标缓冲区的指针。
nSize | pszDest 缓冲区的大小（字节）。 如果 nSize == 0，则函数不进行任何转换， 并原样返回 pszDest，不做任何更改。

返回值：

如果成功，则返回目标字符串。

备注：

无

另请参阅：

STR_TO_WSTR()

返回函数列表

WSTR_TO_UTF8()

注意：建议不使用此函数， 而使用 WSTRTOUTF8()。

说明：

此函数用于将宽字符串转换为 UTF8 字符串。

原型：

boolean WSTR_TO_UTF8
(
const AECHAR * pSrc,
int nLen,
byte * pDst,
int nSize
)

参数：

pSrc | 输入字符串。
nLen | 输入字符串的长度（以 AECHAR 为单位）。
pDst | 目标字符串。
nSize | 目标的大小（字节）。

返回值：

如果成功，则返回 TRUE。

如果失败，则返回 FALSE。

备注：

无

另请参阅：

WSTR_TO_UTF8()

返回函数列表

WSTRCAT()

说明：

此函数用于将 src 字符串附加到 dest。 src 中直至第一个 NULL 之前的所有字符
（包括 NULL 字符）都将添加至 dest。 src 和 dest 均为宽字符串。

原型：

AECHAR * WSTRCAT(AECHAR * pDest, const AECHAR * pSrc)

参数：

pDest | 指向以 NULL 结尾的目标字符串的指针
pSrc | 指向以 NULL 结尾的源字符串的指针

返回值：

指向目标字符串的指针。

备注：

无

另请参阅：

STRCAT()

返回函数列表

WSTRCHR()

说明：

此函数对应于宽字符串的 STRCHR()， 其行为与 STRCHR() 相同。 此函数始终使用宽字符串作为输入。

原型：

AECHAR * WSTRCHR(const AECHAR * s1, AECHAR c)

参数：

s1 | 要搜索的以 NULL 结尾的宽字符串。
c | 要定位的字符

返回值：

指向 s1 中首次出现的 c 的指针

如果找不到 c，则返回 NULL

备注：

无

另请参阅：

STRCHR()

返回函数列表

WSTRCMP()

说明：

此函数用于按字典顺序比较两个字符串，s1 和 s2， 并返回指示比较结果的整数值。
在本函数中，将同等处理 NULL 字符串指针和空字符串。 s1 和 s2 均为宽字符串。

原型：

int WSTRCMP(const AECHAR * s1, const AECHAR * s2)

参数：

s1 | 指向第一个字符串（以 NULL 结尾）的指针
s2 | 指向第二个字符串（以 NULL 结尾）的指针

返回值：

如果 string1 小于 string2，则返回值 < 0

如果 string1 等于 string2，则返回 0（零）

如果 string1 大于 string2，则返回值 > 0

备注：

无

另请参阅：

STRCMP()

返回函数列表

WSTRCOMPRESS()

说明：

此函数用于压缩输入宽字符串。 如果字符小于或等于 127，则函数将把双字节减为单字节。

原型：

void WSTRCOMPRESS
(
const AECHAR * pSrc,
int nLen,
byte * pDest,
int nSize
)

参数：

pSrc | 以 NULL 结尾的源字符串
nLen | 源字符串的长度（以 AECHAR 为单位）
pDest | 指向目标缓冲区的指针
nSize | 目标缓冲区的大小（字节）

返回值：

无

备注：

无

另请参阅：

STRLEN()

返回函数列表

WSTRCPY()

说明：

此函数用于将 src 字符串复制到 dest 中。 src 和 dest 均为宽字符串。

原型：

AECHAR * WSTRCPY(AECHAR * pDest, const AECHAR * pSrc)

参数：

pDest | 指向目标缓冲区的指针
pSrc | 指向必须复制到 pDest 中的字符串（以 NULL 结尾）的指针

返回值：

指向目标字符串的指针。

备注：

无

另请参阅：

WSTRNCOPYN()

STRCPY()

返回函数列表

WSTRDUP()

说明：

此函数用于复制现有的宽字符串。 它首先使用 CREATEOBJ() 分配保存进入字符串拷贝所需的内存，再将该字符串复制到新分配的缓冲区中， 然后从函数返回新分配的缓冲区。 使用后，必须使用 FREEOBJ() 释放缓冲区。

原型：

AECHAR * WSTRDUP(const AECHAR * pIn)

参数：

pIn
指向以 NULL 结尾的宽字符串的有效指针

返回值：

如果成功，则返回包含进入字符串 pIn 拷贝的指针。 使用该指针后，必须使用 FREEOBJ() 将其释放。

如果失败，则返回 NULL。

备注：

无

另请参阅：

无

返回函数列表

WSTRLCAT

说明：

此函数用于将宽字符串连接至目标缓冲区，并确保它以 NULL 结束。

原型：

size_t WSTRLCAT(AECHAR * dst, const AECHAR * src, size_t nSize);

参数：

dst | 目标字符串。 要连接到的字符串。
src | 源字符串。 要复制的字符串。
nSize | 目标缓冲区大小（以 AECHAR 为单位）。

返回值：

作为连接结果而尝试创建的整个字符串的长度。

如果出现错误，则返回 (size_t)-1。

备注：

要查看是否发生截断，可以对比目标缓冲区的长度，检查返回值。

另请参阅：

WSTRCAT()

STRCAT()

返回函数列表

WSTRLCPY()

说明：

此函数用于将宽字符串复制到目标缓冲区中，并确保它以 NULL 结尾。

原型：

size_t WSTRLCPY(AECHAR * dst, const AECHAR * src, size_t nSize);

参数：

dst | 目标字符串。 要复制到的字符串。
src | 源字符串。 要复制的字符串。
nSize | 目标缓冲区大小（以 AECHAR 为单位）。

返回值：

尝试复制的整个字符串的长度。

如果出现错误，则返回 -1。

备注：

要查看是否发生截断，可以对比目标缓冲区的长度，检查返回值。

另请参阅：

WSTRCPY()

WSTRNCOPYN()

STRLCPY()

返回函数列表

WSTRLEN()

说明：

此函数用于获取以 NULL 结尾的给定宽字符串的长度。

原型：

int WStrLen(const AECHAR * str)

参数：

str
需要确定其长度的有效字符串(以 NULL 结尾)

返回值：

返回字符串中的 AECHAR 字符数，不包括结尾的 NULL。

备注：

无

另请参阅：

STRLEN()

返回函数列表

WSTRLOWER()

说明：

此函数用于将宽字符串中的所有大写字符转换为小写。

原型：

void WSTRLOWER(AECHAR * pszDest)

参数：

pszDest
输入时，为指向以 NULL 结尾的源字符串的指针。 返回时，该缓冲区包含已转换的字符串。

返回值：

无

备注：

无

另请参阅：

WSTRUPPER()

返回函数列表

WSTRNCMP()

说明：

此函数用于按字典顺序对两个字符串 s1 和 s2 中至多 length 个字符进行比较， 并返回指示比较结果的整数值。 此函数同等处理 NULL 字符串指针和空字符串。 s1 和 s2 均为 AECHAR 字符组成的宽字符串。

原型：

int WSTRNCMP(const AECHAR * s1, const AECHAR * s2, unsigned int length)

参数：

s1 | 指向第一个字符串（以 NULL 结尾）的指针
s2 | 指向第二个字符串（以 NULL 结尾）的指针
length | 要比较的最大 AECHARS 数

返回值：

如果 s1 == s2，则返回 0（零）

如果 s1 > s2，则返回值 > 0

如果 s1 < s2，则返回值 < 0

备注：

无

另请参阅：

STRNCMP()

返回函数列表

WSTRNCOPYN()

说明：

此函数用于将指定长度的源字符串复制到目标中。 目标必须确保以 NULL 结尾。
src 和 dest 均为宽字符串。

原型：

int WSTRNCOPYN
(
AECHAR * pDest,
int cbDest,
const AECHAR * pSrc,
int lenSource
)

参数：

pDest | [out] | 指向目标缓冲区的指针
cbDest | [in] | pDest 的大小（以 AECHAR 为单位）
pSrc | [in] | 指向必须复制到 pDest 中的字符串（以 NULL 结尾）的指针
lenSource | [in] | 要复制到 pDest 中的字符串最大长度， 不包括 NULL 字符。 如果设为 -1，则将整个 pSrc 都复制到 pDest 中

返回值：

已复制的字符数

备注：

无

另请参阅：

WSTRCPY()

返回函数列表

WSTRRCHR()

说明：

此函数对应于宽字符串的 STRRCHR()， 其行为与 STRRCHR() 相同。 此函数始终使用宽字符串作为输入。

原型：

AECHAR * WSTRRCHR(const AECHAR * s1, AECHAR c)

参数：

s1 | 要搜索的以 NULL 结尾的宽字符串。
c | 要定位的字符

返回值：

指向 s1 中首次出现的 c 的指针。

如果找不到 c，则返回 NULL

备注：

无

另请参阅：

STRRCHR()

返回函数列表

WSTRSIZE()

说明：

此函数用于返回宽字符串的大小（字节）。

原型：

int WSTRSIZE(const AECHAR * p)

参数：

p
指向以 NULL 结尾的宽字符串的有效指针

返回值：

如果成功，则返回宽字符串的大小（字节），包括 NULL 终止符；如果字符串为空，则返回 0。

例如：

WSTRSIZE("") == 0 （空字符串）
WSTRSIZE("h") == 4 ( ('h' + '\0') * sizeof(AECHAR) )

备注：

无

另请参阅：

无

返回函数列表

WSTRTOFLOAT()

说明：

此函数用于将宽字符串转换为浮点值。 函数内部首先使用 WSTRTOSTR() 将给定的宽字符串转换为单字节字符串，然后使用标准 C 库函数 atof() 将单字节字符串转换为双精度值。

原型：

double WSTRTOFLOAT(const AECHAR * psz)

参数：

psz
指向必须转换为浮点值的宽字符串（以 NULL 结尾）的指针。

返回值：

如果成功，则返回给定字符串的浮点值。

否则，返回 0.0。

备注：

无

另请参阅：

FLOATTOWSTR()

返回函数列表

WSTRTOSTR()

说明：

此函数用于将宽字符串转换为单字节字符串。

原型：

char * WSTRTOSTR(const AECHAR * pIn, char * pszDest, int nSize)

参数：

pIn | 指向必须转换为单字节字符串的宽字符串（以 NULL 结尾）的指针
pszDest | 指向接收单字节字符串的目标缓冲区的指针
nSize | pszDest 缓冲区的大小（字节）。 如果 nSize == 0，则函数不进行任何转换， 并原样返回 pszDest，不做任何更改。 nSize 为负值则无效。

返回值：

如果成功，则返回目标字符串

备注：

无

另请参阅：

STRTOWSTR()

返回函数列表

WSTRTOUTF8()

说明：

此函数用于将宽字符串转换为 UTF8 字符串。

原型：

boolean WSTRTOUTF8
(
const AECHAR * pSrc,
int nLen,
byte * pDst,
int nSize
)

参数：

pSrc | 输入字符串
nLen | 输入字符串的长度（以 AECHAR 为单位）
pDst | 目标字符串
nSize | 目标的大小（字节）

返回值：

如果成功，则返回 TRUE

如果失败，则返回 FALSE

备注：

无

另请参阅：

UTF8TOWSTR()

返回函数列表

WSTRUPPER()

说明：

此函数用于将宽字符串中的所有小写字符转换为大写。

原型：

void WSTRUPPER(AECHAR * pszDest)

参数：

pszDest
输入时，为指向以 NULL 结尾的源字符串的指针。 返回时，该缓冲区包含已转换的字符串。

返回值：

无

备注：

无

另请参阅：

WSTRLOWER()

返回函数列表

WWRITELONG()

说明：

此函数用于以零结束字符串的形式写入十进制值 n。

原型：

AECHAR *WWRITELONG(AECHAR *pszBuf, long n);

参数：

pszBuf | [out] | 指向要写入已转换长整型数的宽字符串（以 null 结尾）的有效指针
n | [in] | 输入的长整型数

返回值：

返回指向结尾 NULL 字符的指针。

备注：

pszBuf[] 必须至少可以容纳 12 个字符（'-' + 10 位 + '\0'）

另请参阅：

WSPRINTF()

WWRITELONGEX()

返回函数列表

WWRITELONGEX()

说明：

此函数用于将长整型数转换为宽字符串。 字符串可以使用宽字符 '0' 填充，并可以根据参数 nPad 和 nRemaining 只包含长整型输入值的一部分。

原型：

AECHAR * WWRITELONGEX
(
AECHAR * pszBuf,
long n,
int nPad,
int * pnRemaining
)

参数：

pszBuf | [out] | 指向要写入已转换长整型数的宽字符串（以 NULL 结尾） 的有效指针
n | [in] | 输入的长整型数
nPad | [in] | 指定填充的最大数量。 nPad 值必须小于 12，否则将被忽略。 填充是最终字符串中必须显示的位数。 例如，如果将 n 设为 245，并将 nPad 设为 5，则输出字符串将包含 00245。如果该值大于或等于 12，或小于表示该数字所需的最小值，则将忽略它。 例如，如果将 n 设为 245，并将 nPad 设为 1，则会忽略它。 如果将 npad 设为 0 或负数，也会忽略它。
nRemaining | [in/out] | 输入时，该指针指向指定 pszBuf 大小的整数。 该大小是以字符总数 (AECHAR) 说明。 输出时，该指针指向表示 pszBuf 中剩余的未使用空间 （以 AECHAR 为单位）的整型数。 输出和输入的差值表示写入 pszBuf 中的字符数（不包括 NULL 字符）。

返回值：

指向 pszBuf 未使用部分开始处的指针。 它是在 pszBuf 中写入格式化宽字符串后的部分。

如果失败，则返回 NULL

备注：

无

另请参阅：

WSPRINTF()

WWRITELONG()

返回函数列表

ZEROAT()

说明：

此函数是调零结构的 MEMSET 包装。

原型：

void ZEROAT(ptr)

参数：

ptr
指向零输出的指针

返回值：

无

备注：

该函数很有帮助，使您可以不必记住 MEMSET 参数的顺序

另请参阅：

MEMSET()

返回函数列表


数据类型

本节说明 BREW API 函数所使用的数据类型。 这些数据类型定义了应用程序传递给 BREW 函数及应用程序接收到的数据的格式和内容。 BREW 数据结构的类型定义包含在 BREW 头文件中。 一些数据结构特定于某种 BREW 接口，并包含在那些接口的头文件中。 其它数据结构则可供多个接口使用，并包含于 AEE.h 和 AEEError.h 文件中。每个 BREW 函数说明都包含了到所有相关数据结构说明的链接。

BREW 数据结构有三种主要类型：

  • 结构和联合：一些 BREW 函数使用结构指针作为输入参数。 要使用此类函数，
    需提供一个结构实例，并在调用函数时传递指向该实例的指针。 其它 BREW 函数则返回结构指针作为输出。 本部分将逐一说明每个 BREW 结构中的字段。
  • 枚举类型：有的 BREW 变量和结构成员从 C typedef 枚举结构所定义的有限集中取值。 例如，文本绘制函数所支持的字体类型即由枚举类型定义指定。 本部分将逐一说明每个枚举类型的值。
  • 常量定义：BREW 函数使用的常量是由 #define 结构定义。 常量的一种常见用法是定义一组位掩码，以测试和设置位向量变量中的位值。 每个控件定义一组位掩码常量，用于测试和设置各种控件属性值。 本部分将逐一说明各组相关常量。

数据结构列表

此接口的数据结构包括：

AECHAR

AEE 小程序标记

AEE 事件

AEE IImage 参数

AEE IMenuCtl 属性

AEE ITextCtl 属性

AEE ITimeCtl 属性

AEE 优先级

AEE 标准控件属性

AEE 静态属性

AEE_ADDR_RECID_NULL

AEEAddrCat

AEEAddrField

AEEAddrFieldID

AEEAddrFieldInfo

AEEAlgorithmHint

AEEAppInfo

AEEAppStart

AEEArc

AEEBitmapInfo

AEEBTAddr

AEEBTAGCmd

AEEBTAGEvent

AEEBTAGConnectmode

AEEBTAGInfo

AEEBTDevice

AEEBTDeviceListResult

AEEBTDeviceName

AEEBTDeviceNameResult

AEEBTServerChannel

AEEBTServerChannelResult

AEECallback

AEECircle

AEEClip

AEEClipShape

AEEClrItem

AEEDBField

AEEDBFieldName

AEEDBFieldType

AEEDeviceInfo

AEEDeviceItem

AEEDNSClass

AEEDNSItem

AEEDNSResult

AEEDNSType

AEEEllipse

AEEFileInfoEx

AEEFileUseInfo

AEEFont

AEEFontInfo

AEEFrameType

AEEGPSConfig

AEEGPSInfo

AEEGPSIPServer

AEEGPSMode AEEGPSOpt

AEEGPSServer

AEEGPSSvrType

AEEHANDLER

AEEHandlerType

AEEImageInfo

AEEItemStyle

AEEItemType

AEELicenseType

AEELine

AEEMatrixTransform

AEEMediaCmdNotify

AEEMediaData

AEEMediaMIDISpec

AEEMediaMP3Spec

AEEMediaSeek

AEEMenuColors

AEEMenuColorsMask

AEEMenuSortType

AEENetStats

AEENotify

AEENotifyStatus

AEEPaintMode

AEEPie

AEEPoint

AEEPolygon

AEEPolyline

AEEPosAccuracy

AEEPositionInfo

AEEPriceType

AEEPromptInfo

AEERasterOp

AEERect

AEEResBlob

AEERingerCat

AEERingerCatID

AEERingerEvent

AEERingerID

AEERingerInfo

AEERLP3Cfg

AEESectorInfo

AEESMSTextMsg

AEESoundAPath

AEESoundCmd

AEESoundCmdData

AEESoundDevice

AEESoundInfo

AEESoundMethod

AEESoundMuteCtl

AEESoundPlayerAudioSpec

AEESoundPlayerCmd

AEESoundPlayerCmdData

AEESoundPlayerFile

AEESoundPlayerInfo

AEESoundPlayerInput

AEESoundPlayerMIDISpec

AEESoundPlayerMP3BitRate

AEESoundPlayerMP3Channel

AEESoundPlayerMP3Emphasis

AEESoundPlayerMP3Extension

AEESoundPlayerMP3Layer

AEESoundPlayerMP3SampleRate

AEESoundPlayerMP3Spec

AEESoundPlayerMP3Version

AEESoundPlayerSource

AEESoundPlayerStatus

AEESoundStatus

AEESoundTone

AEESoundToneData

AEESpriteCmd

AEESuspendReason

AEESymbol

AEETextInputMode

AEETextInputModeInfo

AEETileMap

AEETriangle

AEEVoicePrompt

BeepType

CtlAddItem

CtlValChange

DialogInfo

DialogInfoHead

DialogItem

DialogItemHead

DIRECTORY_CHAR

DIRECTORY_STR

DListItem

FileAttrib

FileInfo

FileSeekType

GetLine

HVFocusType

HViewFocus

HViewJump

HViewNotify

HVNotifyCode

HtmlViewer 选项 ID

HtmlViewer 属性标记

IDC_COMMAND_RESERVED

IDISPLAY 标记

IDIB

IGRAPHICS 标记

ISocketCloser

ISocketQI

ITransform 属性

ITField

IVocoderConfigType

IVocoderInfoType

JulianType

NativeColor

NetMgrEvent

NetSocket

NetState

OpenFileMode

PFNAEEEVENT

PFNDATA

PFNCBCANCEL

PFNCONNECTCB

PFNHVIEWNOTIFY

PFNIMAGEINFO

PFNMEDIANOTIFY

PFNMENUSORTCOMPARE

PFNNETMGREVENT

PFNNOTIFY

PFNPOSITIONCB

PFNRINGEREVENT

PFNSMSSTATUS

PFNSOCKETCLOSE

PFNSOUNDPLAYERSTATUS

PFNSOUNDSTATUS

PFNWEBHEADER

PFNWEBSTATUS

PhoneState

RESBLOB_DATA

ResType

RGBVAL

SockIOBlock

Sprite 属性

SSLInfo

SSLSecurityInfo

TAPIStatus

TChType

Tile 属性

Tile 贴图属性

UrlParts

WebFormField

WebOpt

WebRespInfo

WebStatus

X509BasicCert

X509CertPart

X509PartRequest

X509RSAKey

X509TrustOverride

X509TrustResult

有关详细信息，请参阅 BREW SDKTM AEE 分层结构图表

AECHAR

说明：

AECHAR 是 BREW 为宽字符串定义的数据类型。

定义：

typedef uint16 AECHAR;

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEE 小程序标记

说明：

小程序特定的标记。

定义：

AFLAG_HIDDEN | 隐藏小程序。
AFLAG_CFG | 小程序包含 CFG 菜单。
AFLAG_SYSTEM_CFG | 小程序包含隐藏的 CFG 菜单。
AFLAG_TOOL | 小程序为工具。
AFLAG_GAME | 小程序为游戏。
AFLAG_PIM | 小程序为 PIM。
AFLAG_WEB | 小程序为 Web 小程序。
AFLAG_STATIC | 仅供系统使用。
AFLAG_SCREENSAVER | 小程序为屏幕保护程序。
AFLAG_DYNAMIC | 仅供系统使用。

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEE 事件

说明：

将由小程序或控件接收的已定义 AEE 事件。 对于每个事件，都将提供传递给小程序或控件的 wParam 和 dwParam 参数（如果有）。

定义：

下表列出了 BREW 支持的事件代码和按键代码。

按键代码由 EVT_KEY、EVT_KEY_PRESS、EVT_KEY_RELEASE 和 EVT_KEY_HELD 事件传递并接收。


事件代码

事件代码 | 说明 | 参数
EVT_ALARM | 警报事件。 | wParam = 警报代码，dwParam = 0。
EVT_APP_BROWSE_FILE | 在 EVT_APP_START 之后调用。 |
EVT_APP_BROWSE_URL | 在 EVT_APP_START 之后调用 | dwParam = (const AECHAR * pURL)。
EVT_APP_CONFIG | 其它应用程序启动。 显示配置屏幕。 | wParam = 0, dwParam = 0。
EVT_APP_HIDDEN_ CONFIG | 其它应用程序启动。 隐藏配置屏幕。 | wParam = 0，dwParam = 0。
EVT_APP_NO_CLOSE | 不得关闭应用程序 |
EVT_APP_NO_SLEEP | 应用程序正在运行 运行应用程序很长时间之后调用 |
EVT_APP_RESUME | 应用程序恢复。 | wParam = 0，dwParam = 0。
EVT_APP_START | 应用程序启动。 | wParam = 0，dwParam = const char *(参数)。
EVT_APP_STOP | 应用程序停止。 | wParam = 0，dwParam = boolean *(指示应用程序要立即关闭还是稍后关闭的标记)。 默认为立即关闭。
EVT_APP_SUSPEND | 应用程序中止。 | wParam = 0，dwParam = 0。
EVT_BUSY | 发送到应用程序以确定是否中止或停止该应用程序。 如果不想中止或停止，应用程序必须返回 TRUE。 通常情况下，应用程序返回 FALSE。 | wParam = 0，dwParam = 0。
EVT_CB_COPY | 复制请求 - | dwParam = (const char *) const char * 指示首选格式， NULL 表示复制全部
EVT_CB_CUT | 剪切请求 - | dwParam = (const char *) const char * 指示首选格式， NULL 表示剪切全部
EVT_CB_PASTE | 粘贴请求 - | 无参数
EVT_CHAR | 字符事件。 | wParam = 字符的 AECHAR 代码，dwParam = 修改键的位标记。
EVT_COMMAND | 应用程序自定义控件事件。 | wParam = 用户命令 ID，dwParam = 用户数据。
EVT_COPYRIGHT_END | 对话框事件： 版权对话框结束。 | wParam = DialogID，dwParam = IDialog *。
EVT_CTL_ADD_ITEM | 添加项目的消息接口。 | wParam = 0，dwParam = CtlAddItem *。
EVT_CTL_CHANGING | 更改控件事件。 | wParam = 0，dwParam = CtlValChange*。
EVT_CTL_MENU_OPEN | 在菜单激活之前由 ITextCtl 发出。 | wParam = 0，dwParam = IMenuCtl *。
EVT_CTL_SEL_CHANGED | 更改选择后由 IMenuCtl 发出 | wParam - 选项 ID，dwParam == IMenuCtl *
EVT_CTL_SET_TEXT | 设置文本控件事件。 | wParam = ID，dwParam = 如果 ID 非零，则为资源文件，否则为文本。
EVT_CTL_SET_TITLE | 设置控件标题事件。 | wParam = ID，dwParam = 如果 ID 非零，则为资源文件，否则为文本。
EVT_CTL_SKMENU_PAGE_FULL | SK 菜单页满时由 IMenuCtl 发出 | dwParam == IMenuCtl *
EVT_CTL_TAB | 应用程序选项卡事件。 | wParam = 0-左，1-右；dwParam = 指向控件的指针。
EVT_CTL_TEXT_ MODECHANGED | 更改文本输入模式后由 ITextCtl 发出。 它可能是用户通过软键更改输入模式，或程序使用 ITEXTCTL_SetInputMode() 更改文本控件输入模式所生成 |
EVT_DIALOG_END | 对话框事件： 对话框正常完成。 | wParam = DialogID，dwParam = IDialog *。dwPram 含有 1 表示从用户处获得“是”响应，2 表示“否”响应。
EVT_DIALOG_INIT | 对话框事件： 创建控件，预初始化值、标记和其它项。 | wParam = DialogID，dwParam = IDialog *。
EVT_DIALOG_START | 对话框事件： 对话框打开。 | wParam = DialogID，dwParam = IDialog *。
EVT_FLIP | 设备特定事件： 开关翻盖式（蛤式外壳）设备时发送到应用程序。 | wParam = TRUE（已打开），FALSE（已关闭）；dwParam = 0。
EVT_KEY | 按键处理事件。 | wParam = 按键代码（参见按键代码表），dwParam = 修改键的位标记。
EVT_KEY_HELD | 按键保持事件。 按键保持时间取决于特定设备。 Emulator 不支持。 | wParam = 按键代码（参见按键代码表），dwParam = 修改键的位标记。
EVT_KEY_PRESS | 按键事件。 | wParam = 按键代码（参见按键代码表），dwParam = 修改键的位标记。
EVT_KEY_RELEASE | 松开按键事件。 | wParam = 按键代码（参见按键代码表），dwParam = 修改键的位标记。
EVT_KEYGUARD | 设备特定事件： 锁定设备键盘时发送到应用程序。 | wParam = 如果键盘打开， 则为 TRUE，否则为 FALSE；dwParam = 0。
EVT_LOCKED | 设备特定事件： 锁定设备用户接口时发送到应用程序。 | wParam = 如果锁定设备用户接口，则为 TRUE，否则为 FALSE；dwParam = 0。
EVT_MOD_LIST_CHANGED | 更改模块列表。 可能在应用程序中止后发送！ |
EVT_NOTIFY | BREW 生成的通知或应用程序注册的通知事件。 | wParam = 0，dwParam = AEENotify *。
EVT_UPDATECHAR | 更新字符事件。 | wParam = 字符的 AECHAR 代码，dwParam = 修改键的位标记。
EVT_USER | 启动应用程序或用户定义事件。 | 应用程序专用。

成员：

无

备注

用户定义事件从 EVT_USER 启动。

另请参阅：

无

返回数据结构列表

AEE IImage 参数

说明：

为 IImage 接口定义的参数。

定义：

IPARM_SIZE | 要显示的图像的实际大小。
IPARM_OFFSET | 必须用于显示的整个图像内的偏移量。
IPARM_CXFRAME | 一般不支持动画的格式（如 Windows BMP）的每帧宽度。
IPARM_NFRAMES | 帧数。
IPARM_RATE | 动画速度（以毫秒为单位）。
IPARM_ROP | 绘制图像时要使用的“光栅”操作。
IPARM_OFFSCREEN | 指定是否将图像绘制到后台屏幕缓冲区。

成员：

无

备注：

无

另请参阅：

IIMAGE_SetParm()

返回数据结构列表

AEE IMenuCtl 属性

说明：

为 IMenuCtl 接口定义的属性。

定义：

MP_WRAPSCROLL | 如果已设置，则在滚动到屏幕底端时将上卷循环 （仅用于“软键”和“列表”控件）。
MP_NO_ARROWS | 如果已设置，即使可以滚动也没有箭头。
MP_NO_REDRAW | 如果已设置，则不能在调用 IMENUCTL_SetActive() 或改变选择时，内部调用 IMENUCTL_Redraw() 函数。
MP_UNDERLINE_TITLE | 如果已设置，将为标题加下划线。
MP_PAGESCROLL | 如果已设置，则按页滚动；否则为平滑滚动。

仅对菜单控件对象的标准菜单或软键列表视图有效的属性：

MP_BI_STATE_IMAGE | 如果已设置，则没有边框的图像将有两种状态 （未选择或已选择）。
MP_TRI_STATE_IMAGE | 如果已设置，则没有边框的图像将有三种状态 （未选择、已选择或按下）。
MP_MAXSOFTKEYITEMS | 如果已设置，将显示每屏最多可以显示的软键项数。

仅对菜单控件对象的图标列表视图有效的属性：

MP_ICON_TEXT_TOP
如果已设置，则图标视图： 文本位于顶部。
MP_ICON_SINGLE_FRAME
如果已设置，则图标视图： 单帧。
MP_ICON_DELAY_IMAGE
如果已设置，则延迟单帧图像。
MP_ICON_ANIMATED
如果已设置，则动画选定图标（假定为动画类型或方形图像）。
如果设置了 MP_ICON_ANIMATED 属性，并且图像形状的宽度恰好为高度的倍数，则将根据宽度与高度的倍数把图像分成方块并制成动画。 示例： 如果图像宽为 80 高为 20，且设置了 MP_ICON_ANIMATED 属性，则此图像将被分成 4 帧 20X20 的方形并制成动画。
MP_ICON_NO_CENTERSEL
对于高度只够显示单行图标的图标控件菜单，如果菜单中有多个可以显示的项，则选中的项始终保持居中。 此行为是默认行为，它与菜单中的项少于可显示项时的行为不相同。 该属性将使工具栏行为在以下两种情况中保持一致：
  • 可以显示的项数目 < 菜单项的数目
  • 可以显示的项数目 > 菜单项的数目
MP_BI_STATE_IMAGE
没有边框的图像将有两种状态（未选择/已选择）。
MP_TRI_STATE_IMAGE
没有边框的图像将有三种状态（未选择/已选择/按下）。

仅对菜单控件对象的日历视图有效的属性：

MP_CALENDAR
如果已设置，MP_CALENDAR（参见插图）将允许在日程程序中使用标准菜单作为“日期视图”。
在菜单项之间绘制水平线，每项表示特定钟点的日程约会
如果左上角出现小方框，则表示下午。 无方框则表示上午。
每个菜单项的高度与它的持续时间成正比。
使用设备的数字键选择约会钟点，应用程序还可设置说明约会的菜单项文本。
菜单右边缘的三角形表示当前时间。
（参见插图）
MP_AUTOSCROLLTIME
如果已设置，将自动滚动“日程视图”菜单，以便在显示日历时将对应于当前时间的条目显示在屏幕上。只有在使用 bActive=TRUE 调用 IMENUCTL_SetActive()，
并且菜单当前“不”活动，才会出现这种情况。 之后还需要调用 IMENUCTL_Redraw()。

只对软键和纯菜单控件有效的属性

MP_MULTI_SEL | 如果已设置，则允许按下多个条目。
MP_MAXSOFTKEYITEMS | 如果已设置，则菜单允许多项选择。 不能与双态或三态图像属性一起使用。 (uint16)-1 是该类型的一个特殊标记， 不允许将项设为此值。

成员：

无

备注

如果使用 MP_BI_STATE_IMAGE 设置 MP_MULTI_SE，则将出现小的选择方框，
并显示具有当前选中焦点的项的文本。

如果使用 MP_TRI_STATE_IMAGE 设置 MP_MULTI_SEL，则不会有方框，图像状态将指示用户该项是否为未选择/已选择/选定。 如果已设置 MP_MULTI_SEL 样式，
建议对菜单项使用文本。

另请参阅：

IMENUCTL_SetProperties()

IMENUCTL_GetProperties()

返回数据结构列表

AEE ITextCtl 属性

说明：

为 ITextCtl 接口定义的属性。

定义：

TP_MULTILINE | 如果已设置，则文本控件对象为多行控件。
TP_FRAME | 如果已设置，则文本控件对象将具有外框。
TP_T9_MODE | 如果已设置，则文本控件对象将使用 T9 模式。 (TP_RAPID_MODE)
TP_RAPID_MODE | 支持快速输入（为默认设置）
TP_NODRAW | 控件禁用所有绘制操作
TP_NOUPDATE | 禁用无用的 IDISPLAY_Update() 调用
TP_PASSWORD | 显示 ***，管理正确的缓冲区字符
TP_INTEGRALHEIGHT | 如果已设置，它将强制 ITEXTCTL_SetRect() 矩形的高度为根据字符高度计算的平均高度。 基本没有剩余空间，文本控件将恰好容纳文本。 文本控件不显示 1.5 行文本，而显示 1 行或 2 行。它将调整至最接近的行高度并固定为该值。
TP_FIXSETRECT | 实际高度更接近地表示请求高度。

成员：

无

备注

无

另请参阅：

ITEXTCTL_SetProperties()

ITEXTCTL_GetProperties()

返回数据结构列表

AEE ITimeCtl 属性

说明：

为 ITimeCtl 接口定义的属性。

定义：

TP_AUTOREDRAW | 如果已设置，则在 SetActive 时刷新。
TP_NO_SECONDS | 如果已设置，则“倒数计时”控件中不显示秒。
TP_NO_MSECONDS | 如果已设置，则“秒表”中不显示毫秒。
TP_NOEDIT_AMPM | 如果已设置，将不允许编辑 AM/PM。
TP_LEFT_JUSTIFY | 如果已设置，则左对齐绘制文本（默认为居中）。

成员：

无

备注：

无

另请参阅：

ITIMECTL_SetProperties()

ITIMECTL_GetProperties()

返回数据结构列表

AEE 优先级

说明：

以下标记定义了应用程序可以拥有的优先级。 应用程序可拥有 0（零）或更多优先级，它们均内部保存在一个位向量中。 这些标记可用于测试和设置该向量中每个优先级的位值。

定义：

无

成员：

PL_FILE | 应用程序拥有创建和写入文件及数据库的权限。
PL_NETWORK | 应用程序可以访问 INetMgr 接口和 ISocket 接口的函数。
PL_TAPI | 应用程序可以访问通话函数。
PL_DOWNLOAD | 应用程序可以访问 IDownload 接口，该接口包含访问 BREW 应用程序下载服务器的函数（此优先级仅供运营商和设备制造商使用）。
PL_SHARED_WRITE | 应用程序拥有访问共享应用程序目录的权限，使应用程序可以共享文件。
PL_POS_LOCATION | 应用程序可以访问定位函数（目前尚不支持）。
PL_SYSTEM | 应用程序拥有上述所有优先级和附加函数（该优先级仅供运营商和设备制造商使用）。
PL_WEB | 如果已设置，则允许应用程序实例化 IWeb。 PL_NETWORK 是 PL_WEB 的超级权限。 注意： 如果拥有 PL_WEB，便可获取 IWeb。 如果拥有 PL_NETWORK，便可获取 INetMgr/ISocket 和 IWeb。
PL_RINGER_WRITE | 如果已设置，则允许应用程序创建 IRINGERMGR_Create() 振铃器音调。 播放振铃器音调不需要优先级设置。
PL_SECTORINFO | 如果已设置，则允许应用程序访问 IPOSDET_GetSectorInfo()。
PL_ADDRBOOK | 如果已设置，则允许应用程序访问地址簿。

备注：

无

另请参阅：

ISHELL_CheckPrivLevel()

返回数据结构列表

AEE 标准控件属性

说明：

已定义的标准控件属性。

定义：

CP_BORDER | 控件具有边框。
CP_STATIC | 控件为静态控件，SetActive 不影响该控件类型。
CP_3D_BORDER | 3D 边框。
CP_USE_DEFAULT | 使用默认属性。
CP_ICON | 控件为三态图像
CP_RESERVED | 保留项

成员：

无

备注

无

另请参阅：

无

返回数据结构列表

AEE 静态属性

说明：

为 IStatic 接口定义的属性。

定义：

ST_CENTERTEXT | 使文本居中排列
ST_CENTERTITLE | 使标题居中排列
ST_NOSCROLL | 不滚动显示文本
ST_TEXTALLOC | 在堆上分配文本 - 对话框负责释放文本。
ST_TITLEALLOC | 在堆上分配标题- 对话框负责释放标题。
ST_MIDDLETEXT | 在屏幕中央绘制文本
ST_UNDERLINE | 为标题加下划线
ST_ICONTEXT | 文本为 IImage *
ST_ASCII | 文本为单字节文本
ST_ENABLETAB | 处于顶部或底部时生成 EVT_CTL_TAB
ST_ENABLE_HLGHT | 突出显示获得焦点的静态控件

成员：

无

备注

无

另请参阅：

ISTATIC_SetProperties()

ISTATIC_GetProperties()

返回数据结构列表

AEE_ADDR_RECID_NULL

说明：

此数据结构用于定义 BREW 地址簿接口中使用的 NULL 记录。

定义：

#define AEE_ADDR_RECID_NULL 0xffff

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEEAddrCat

说明：

AEEAddrCat 用于指定地址类别的 ID

定义：

typedef uint16 AEEAddrCat;

成员：

以下是预定义类别的列表

AEE_ADDR_CAT_NONE | 无类别。
AEE_ADDR_CAT_PERSONAL | 个人记录。
AEE_ADDR_CAT_BUSINESS | 业务记录。
AEE_ADDR_CAT_USER_DEFINED | OEM 定义的类别 ID 的开始范围。
AEE_ADDR_CAT_ERR | 边界限制。

备注：

无

另请参阅：

无

返回数据结构列表

AEEAddrField

说明：

此结构包含每个地址字段的定义。 AddressRecord 是一个或多个 AddressField 的集合。

定义：

typedef structure
{
AEEAddrFieldID fID;
AEEAddrFieldType fType;
void * pBuffer;
uint16 wDataLen;
} AEEAddrField;

成员：

fieldID | 字段 ID（如 WORK_PHONE 或 URL）。
fType | 用于存储该字段数据的数据类型（如 FT_STRING）。
wDataLen | 数据长度（字节）。
pBuffer | 指向实际数据的指针。

备注：

无

另请参阅：

AEEAddrFieldID

AEEAddrFieldType

返回数据结构列表

AEEAddrFieldID

说明：

AEEAddrFieldID 用于指定字段 ID。

定义：

typedef uint16 AEEAddrFieldID;

成员：

以下是预定义字段 ID 的列表。

AEE_ADDRFIELD_NONE |
AEE_ADDRFIELD_FIRSTNAME |
AEE_ADDRFIELD_MIDDLENAME |
AEE_ADDRFIELD_LASTNAME |
AEE_ADDRFIELD_NICKNAME |
AEE_ADDRFIELD_NAME |
AEE_ADDRFIELD_ORG |
AEE_ADDRFIELD_JOBTITLE |
AEE_ADDRFIELD_ADDRESS |
AEE_ADDRFIELD_CITY |
AEE_ADDRFIELD_STATE |
AEE_ADDRFIELD_COUNTRY |
AEE_ADDRFIELD_ZIPCODXE |
AEE_ADDRFIELD_URL |
AEE_ADDRFIELD_DEPARTMENT |
AEE_ADDRFIELD_EMAIL |
AEE_ADDRFIELD_GENDER |
AEE_ADDRFIELD_PHONE_WORK |
AEE_ADDRFIELD_PHONE_HOME |
AEE_ADDRFIELD_PHONE_FAX |
AEE_ADDRFIELD_PHONE_VOICE |
AEE_ADDRFIELD_PHONE_PREF |
AEE_ADDRFIELD_PHONE_CELL |
AEE_ADDRFIELD_PHONE_PAGER |
AEE_ADDRFIELD_PHONE_GENERIC |
AEE_ADDRFIELD_PHONE_OTHER |
AEE_ADDRFIELD_BDAY |
AEE_ADDRFIELD_SORTSTRING | 指定用于按照特定语言顺序排列地址框输入项的系列名称或给定名称。
AEE_ADDRFIELD_NOTES |
AEE_ADDRFIELD_USER_DEFINED | 用户定义的 FieldID 从此处开始
AEE_ADDRFIELD_ERR | 列表中的最后一项

备注：

无

另请参阅：

无

返回数据结构列表

AEEAddrFieldInfo

说明：

AEEAddrFieldInfo 包含地址簿中支持的字段的信息， 用于 IADDRBOOK_EnumNextFieldsInfo() 函数，以获取地址簿中每个支持字段的详细信息。

定义：

typedef structure _AEEAddrFieldInfo
{
AEEAddrFieldID fieldID;
int nMaxItems;
AEEAddrFieldType fType;
boolean bFieldSearch;
boolean bFieldCatSearch;
} AEEAddrFieldInfo;

成员：

fieldID | 字段的 ID。
nMaxItems | 允许每个记录中包含该 fieldID 项的最大数量。
fType | 用于保存该字段信息的数据类型。
bFieldSearch | 指定是否可以根据此字段进行搜索 (EnumRec)。 例如，是否可以调用 IADDRBOOK_EnumRecInit() 来搜索所给定字段为某特定值的全部记录。 此搜索与该记录的类别不相关。 例如，它可以搜索 AEE_ADDRFIELD_NAME 字段为某特定值的所有记录。
bFieldCatSearch | 指定是否可以根据此字段在某个类别内进行搜索 (EnumRec)。 例如，是否可以使用 IADDRBOOK_EnumRecInit() 来搜索特定类别中此字段为某特定值的所有记录。 另一示例： 搜索 AEE_ADDRFIELD_NAME 字段为某特定值的所有 AEE_ADDR_CAT_PERSONAL 记录。 如果此标记为 FALSE，并且 bFieldSearch 为 TRUE，则在 IADDRBOOK_EnumRecInit() 调用中，必须将 AEEAddrCat 的值设置为 AEE_ADDR_CAT_NONE，以便在搜索过程中忽略类别。

备注：

无

另请参阅：

IADDRBOOK_EnumFieldsInfoInit()

IADDRBOOK_EnumNextFieldsInfo()

返回数据结构列表

AEEAlgorithmHint

说明：

该 ENUM 用于指定应用程序要使用哪种算法进行绘制操作。

定义：

typedef enum {ALGORITHM_ACCURATE, ALGORITHM_FAST} AEEAlgorithmHint;

成员：

ALGORITHM_ACCURATE | 该实现对各种输入都比较精确， 但可能会比较慢。
ALGORITHM_FAST | 该实现的速度较快，但对某些较少使用的输入可能不太精确。

备注：

在此版本中，算法提示仅对 IGRAPHICS_DrawPolygon 有效。默认的算法提示为 ALGORITHM_FAST。 对大多数应用程序而言，已经足够； 大多数情况下，结果也是精确的。

另请参阅：

IGRAPHICS_DrawPolygon()

返回数据结构列表

AEEAppInfo

说明：

此结构用于保存有关小程序的信息。

定义：

typedef structure:
{
AEECLSID cls;
char * pszMIF;
uint16 wIDBase;
uint16 wAppType;
uint16 wPad2;
uint16 wPad3;
uint16 wPad4;
uint16 wFlags;
} AEEAppInfo;

成员：

cls | 小程序 ClassID。
pszMIF | 小程序资源文件。
wIDBase | 在小程序资源文件中定位标题、图标和其它项的基本 ID。
wAppType | 增强（运营商定义的）应用程序类型。
wPad2, ... | 更多应用程序类型
wFlags | AEE 小程序标记。

备注：

无

另请参阅：

AEE 小程序标记

AEECLSID 列表

返回数据结构列表

AEEAppStart

说明：

此结构在 EVT_APP_START 或 EVT_APP_RESUME 时发送。

定义：

typedef structure
{
int error;
AEECLSID clsApp;
IDisplay * pDisplay;
AEERect rc;
const char * pszArgs;
} AEEAppStart;

成员：

error | 如有错误，将由应用程序填充。
clsApp | 小程序 ID。
pDisplay | 指向 IDisplay 接口对象的指针。
rc | 小程序矩形。
pszArgs | 指向参数字符串的指针。 这些参数还可以通过 EVT_APP_BROWSE_FILE 或 EVT_APP_BROWSE_URL 输入进行传递。

备注：

无

另请参阅：

AEECLSID 列表

AEERect

返回数据结构列表

AEEArc

说明：

此结构用于定义圆弧数据类型。

定义：

typedef structure _arc
{
int16 cx, cy;
int16 r;
int16 startAngle;
int16 arcAngle;
} AEEArc;

成员：

cx | 参考圆圆心的 X 坐标。
cy | 参考圆圆心的 Y 坐标。
r | 参考圆的半径。
startAngle | 圆弧的起始角度（度）。
arcAngle | 圆弧角度（度）。

备注：

前三个字段与 AEECircle 的相同，这样可以在需要时方便地将 AEEArc 结构显式转换为 AEECircle。

另请参阅：

AEECircle

IGRAPHICS_DrawArc()

IGRAPHICS_Translate()

返回数据结构列表

AEEBitmapInfo

说明：

此结构包含有关 DIB 和 DDB 位图尺寸的所有信息。

定义：

typedef structure
{
uint32 cx;
uint32 cy;
uint32 nDepth;
} AEEBitmapInfo;

成员：

cx | 每行像素数量。
cy | 每列像素数量。
nDepth | 每个像素的位数。

备注：

无。

另请参阅：

无

返回数据结构列表

AEEBTAddr

说明：

AEEBTAddr 用于定义设备的 Bluetooth 地址。

定义：

typedef PACKED struct tagAEEBTAddr
char caddr[6];
GCCPACKED AEEBTAddr;

成员：

caddr - Bluetooth 地址数组

备注：

无

另请参阅：

无

返回数据结构列表

AEEBTAGCmd

说明：

AEEBTAGCmd 用于指定 Bluetooth 音频网关命令。

定义：

typedef int32 AEEBTAGCmd;

成员：

可能的取值：

AEEBT_CMD_RING_HEADSET： 使耳机振铃

AEEBT_CMD_AUDIO_CONNECT： 连接音频通道

AEEBT_CMD_SET_SPKR_GAIN： 增大/减小扬声器增益

AEEBT_CMD_SET_HS_GAIN： 增大/减小耳机增益

AEEBT_CMD_DISCONNECT： 断开音频网关连接

备注：

无

另请参阅：

无

返回数据结构列表

AEEBTAGEvent

说明：

AEEBTAGEvent 用于指定 Bluetooth 音频网关事件。

定义：

typedef int32 AEEBTAGEvent;

成员：

可能的取值：

AEEBT_EV_AG_NOEVENTS： BT 堆栈无其它事件

AEEBT_EV_AG_ENABLED： 已启用 BT 音频网关

AEEBT_EV_AG_DISABLED： 已禁用 BT 音频网关

AEEBT_EV_AG_HEADSET_PICKUP： 用户已连接耳机

AEEBT_EV_AG_DISCONNECT_REQUEST： 用户已断开耳机连接

AEEBT_EV_AG_AUDIO_CONNECTED： 已连接音频通道

AEEBT_EV_AG_AUDIO_DISCONNECTED： 已断开音频通道连接

AEEBT_EV_AG_AUDIO_CONN_TIMEOUT： 连接超时

AEEBT_EV_AG_ERROR： 命令处理期间出错

备注：

无

另请参阅：

无

返回数据结构列表

AEEBTAGConnectmode

说明：

AEEBTAGConnectmode 用于指定正在运行音频网关配置文件

的 Bluetooth 设备的连接模式。

定义：

typedef enum tagAEEBTAGConnectmode
AEEBT_AG_CONN_AG_ORIG_MODE,
AEEBT_AG_CONN_HS_ORIG_MODE
AEEBTAGConnectmode;

成员：

可能的取值：

AEEBT_AG_CONN_AG_ORIG_MODE： 仅 AG 设备的页（客户端模式）。

AEEBT_AG_CONN_HS_ORIG_MODE： 仅 AG 客户端的扫描页（服务器模式）。

备注：

无

另请参阅：

无

返回数据结构列表

AEEBTAGInfo

说明：

AEEBTAGInfo 用于指定请求打开音频网关时 Bluetooth 音频网关的信息。

定义：

typedef PACKED struct tagAEEBTAGInfo
AEEBTAddr bdaddr;
AEEBTRCServerChannel usrvc;
AEEBTAGConnectmode btMode;
GCCPACKED AEEBTAGInfo;

成员：

bdaddr - 耳机 BT 设备地址。

usrvc- 耳机服务器通道号

btMode -连接模式。

备注：

无

另请参阅：

AEEBTAddr

AEEBTServerChannel

AEEBTAGConnectmode

返回数据结构列表

AEEBTDevice

说明：

AEEBTDevice 用于指定设备的 Bluetooth 属性。

定义：

typedef PACKED struct tagAEEBTDevice
AEEBTAddr bdaddr;
uint16 usvcclass;
uint16 uMajorDeviceClass;
uint16 uMinorDeviceClass;
GCCPACKED AEEBTDevice;

成员：

bdaddr - Bluetooth 设备地址

usvclass - 设备的服务类别。 可能的取值为：

AEEBT_SD_SERVICE_CLASS_SERVICE_DISCOVERY_SERVER

AEEBT_SD_SERVICE_CLASS_BROWSE_GROUP_DESCRIPTOR

AEEBT_SD_SERVICE_CLASS_PUBLIC_BROWSE_GROUP

AEEBT_SD_SERVICE_CLASS_SERIAL_PORT

AEEBT_SD_SERVICE_CLASS_LAN_ACCESS_PPP

AEEBT_SD_SERVICE_CLASS_DIALUP_NETWORKING

AEEBT_SD_SERVICE_CLASS_IR_MC_SYNC

AEEBT_SD_SERVICE_CLASS_OBEX_OBJECT_PUSH

AEEBT_SD_SERVICE_CLASS_OBEX_FILE_TRANSFER

AEEBT_SD_SERVICE_CLASS_IR_MC_SYNC_COMMAND

AEEBT_SD_SERVICE_CLASS_HEADSET

AEEBT_SD_SERVICE_CLASS_CORDLESS_TELEPHONY

AEEBT_SD_SERVICE_CLASS_INTERCOM

AEEBT_SD_SERVICE_CLASS_FAX

AEEBT_SD_SERVICE_CLASS_HEADSET_AUDIO_GATEWAY

AEEBT_SD_SERVICE_CLASS_PNP_INFORMATION

AEEBT_SD_SERVICE_CLASS_GENERIC_NETWORKING

AEEBT_SD_SERVICE_CLASS_GENERIC_FILE_TRANSFER

AEEBT_SD_SERVICE_CLASS_GENERIC_AUDIO

AEEBT_SD_SERVICE_CLASS_GENERIC_TELEPHONY

uMajorDeviceClass 此设备的主设备类别。 可能的取值为：

AEEBT_SD_MAJOR_DEVICE_CLASS_MISC

AEEBT_SD_MAJOR_DEVICE_CLASS_COMPUTER

AEEBT_SD_MAJOR_DEVICE_CLASS_PHONE

AEEBT_SD_MAJOR_DEVICE_CLASS_LAN_ACCESS_POINT

AEEBT_SD_MAJOR_DEVICE_CLASS_AUDIO

AEEBT_SD_MAJOR_DEVICE_CLASS_PERIPHERAL

AEEBT_SD_MAJOR_DEVICE_CLASS_UNCLASSIFIED

uMinorDeviceClass 此设备的次要设备类别。 可能的取值为：

AEEBT_SD_MINOR_DEVICE_CLASS_UNCLASSIFIED

AEEBT_SD_MINOR_DEVICE_CLASS_DESKTOP_WORKSTATION

AEEBT_SD_MINOR_DEVICE_CLASS_SERVER_CLASS_COMPUTER

AEEBT_SD_MINOR_DEVICE_CLASS_LAPTOP

AEEBT_SD_MINOR_DEVICE_CLASS_HANDHELD_PC_OR_PDA

AEEBT_SD_MINOR_DEVICE_CLASS_PALM_SIZED_PC_OR_PDA

AEEBT_SD_MINOR_DEVICE_CLASS_CELLULAR

AEEBT_SD_MINOR_DEVICE_CLASS_CORDLESS

AEEBT_SD_MINOR_DEVICE_CLASS_SMART_PHONE

AEEBT_SD_MINOR_DEVICE_CLASS_WIRED_MODEM_OR_VOICE_GATEWAY

AEEBT_SD_MINOR_DEVICE_CLASS_FULLY_AVAILABLE

AEEBT_SD_MINOR_DEVICE_CLASS_1_TO_17_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_17_TO_33_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_33_TO_50_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_50_to_67_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_67_TO_83_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_83_TO_99_PERCENT_UTILIZED

AEEBT_SD_MINOR_DEVICE_CLASS_NO_SERVICE_AVAILABLE

备注：

无

另请参阅：

AEEBTDeviceList

返回数据结构列表

AEEBTDeviceListResult

说明：

AEEBTDeviceListResult 中包含 IBTSDP_DiscoverDevices() 的结果。

定义：

typedef struct tagDevicelist
AEEBTSDPResultCode errcode;
uint8 unumdevices;
AEEBTDevice btdevices[1];
AEEBTDeviceListResult;

成员：

errcode - IBTSDP_DiscoverDevices 请求的错误代码。

unumDevices - 发现的设备数量。

btDevices - 已发现的各种设备的设备规格数组。

备注：

用户应按以下方式分配此结构：

sizeof(AEEBTDeviceListResult) + (unumdevices - 1) * sizeof(AEEBTDevice);.

另请参阅：

AEEBTDevice

返回数据结构列表

AEEBTDeviceName

说明：

AEEBTDeviceName 用于指定设备的 Bluetooth 设备名。 设备名包含设备的 Bluetooth 地址。

定义：

typedef PACKED struct tagAEEBTDeviceName
AEEBTAddr bdaddr;
char szDevName[AEEBT_MAX_DEVICENAME_LEN];
GCCPACKED AEEBTDeviceName;

成员：

bdaddr - 设备的 Bluetooth 地址

szDevName - Bluetooth 设备的名称。

备注：

无。

另请参阅：

AEEBTAddr

返回数据结构列表

AEEBTDeviceNameResult

说明：

AEEBTDeviceNameResult 用于指定返回

IBTSDP_GetDeviceName 请求结果的结构。

定义：

typedef struct tagBTDeviceName
AEEBTSDPResultCode errcode;
AEEBTDeviceName btDeviceName;
AEEBTDeviceNameResult;

成员：

errcode - IBTSDP_DiscoverDevices 请求的错误代码。

btDeviceName 在请求中指定了其地址的设备的 Bluetooth 名称。

备注：

无。

另请参阅：

AEEBTDeviceName

AEEBTAddr

返回数据结构列表

AEEBTRCServerChannel

说明：

AEEBTRCServerChannel 用于指定远程 Bluetooth 设备提供 RMCOMM 服务的 RFCOMM 通道号。

定义：

typedef uint8 AEEBTRCServerChannel;

成员：

无。

备注：

无。

另请参阅：

无。

返回数据结构列表

AEEBTServerChannel

说明：

AEEBTServerChannel 用于指定

远程 Bluetooth 提供特定服务的通道号。

定义：

typedef PACKED struct tagAEEBTServerChannel
AEEBTAddr bdaddr;
uint16 usvcclass;
uint16 uscn;
GCCPACKED AEEBTServerChannel;

成员：

bdaddr - 远程设备的 Bluetooth 地址

usvcclass - 指定服务的服务类别（参见 AEEBTDevice）。

uscn - 服务的通道号。

备注：

另请参阅：

AEEBTAddr

AEEBTDevice

返回数据结构列表

AEEBTServerChannelResult

说明：

AEEBTServerChannelResult 用于指定返回

IBTSDP_GetRemoteServerChannel 请求结果的结构。

定义：

typedef struct tagBTServerChannel
AEEBTSDPResultCode errcode;
AEEBTServerChannel btServerChannel;
AEEBTServerChannelResult;

成员：

errcode - IBTSDP_DiscoverDevices 请求的错误代码。

btServerChannel - 从远程 Bluetooth 设备获取服务的通道规格。

备注：

无

另请参阅：

AEEBTRCServerChannel

返回数据结构列表

AEECallback

说明：

此结构用于指定使用 ISHELL_Resume() 函数注册的回调的数据和函数。

定义：

typedef structure AEECallback; structure _AEECallback
{
AEECallback * pNext;
void * pmc;
PFNCBCANCEL pfnCancel;
void * pCancelData;
PFNNOTIFY pfnNotify;
void * pNotifyData;
void * pReserved;
};

成员：

pNext | 保留，调用者不得修改此成员。
pmc | 保留，调用者不得修改此成员。
pfnCancel | 回调处理程序调用的函数的指针（如果取消该回调）。 调用程序必须将此指针设置为 NULL。
pCancelData | 传递给 pfnCancel 的数据。 调用程序不得修改此成员。
pfnNotify | AEE 调用的回调函数。 调用程序必须将该指针设置为指向 AEE 回调处理程序要调用的函数。
pNotifyData | 将要传递给 pfnNotify 的数据。
pReserved | 保留，回调处理程序将使用该成员。

备注：

无

另请参阅：

无

返回数据结构列表

AEECircle

说明：

此结构用于定义圆数据类型。

定义：

typedef structure _circle
{
int16 cx, cy;
int16 r;
} AEECircle;

成员：

cx | 圆心的 X 坐标。
cy | 圆心的 Y 坐标。
r | 圆周半径（以像素为单位）。

备注：

无

另请参阅：

IGRAPHICS_DrawCircle()

IGRAPHICS_Translate()

返回数据结构列表

AEEClip

说明：

此结构用于定义剪切图形（用于限制区域）的尺寸，IGraphics 绘制操作在该限制区域中生效。

定义：

typedef structure _clipshape
{
AEEClipShape type;
union {
AEERect rect;
AEECircle circle;
AEEEllipse ellipse;
AEEPie pie;
AEETriangle triangle;
} shape;
} AEEClip;

成员：

type | 剪切图形的类型。
shape | 剪切图形的联合。
shape.rect | 矩形剪切图形。
shape.circle | 圆形剪切图形。
shape.ellipse | 椭圆剪切图形。
shape.pie | 饼图剪切图形。
shape.triangle | 三角形剪切图形。

备注：

图形为联合类型， 任意时刻仅有一个图形有效。 程序必须先检查类型，然后访问相应的剪切图形。

另请参阅：

AEEClipShape.

AEERect

AEECircle

AEEEllipse

AEEPie

AEETriangle

返回数据结构列表

AEEClipShape

说明：

此 ENUM 用于指定剪切区域的图形类型。

定义：

typedef enum
{
CLIPPING_NONE,
CLIPPING_RECT,
CLIPPING_CIRCLE,
CLIPPING_ELLIPSE
CLIPPING_PIE,
CLIPPING_TRIANGLE,
CLIPPING_POLYGON
} AEEClipShape;

成员：

CLIPPING_NONE | 未指定剪切图形，将显示窗口用作默认的图形。
CLIPPING_RECT | 矩形。
CLIPPING_CIRCLE | 圆形。
CLIPPING_ELLIPSE | 椭圆。
CLIPPING_PIE | 饼图。
CLIPPING_TRIANGLE | 三角形。
CLIPPING_POLYGON | 任意多边形。

备注：

默认的剪切图形为 CLIPPING_RECT，默认的剪切区域为显示窗口。 通过调用 IGRAPHICS_SetClip()，程序可以更改剪切区域。

另请参阅：

AEEClip

AEERect

AEECircle

AEEEllipse

AEEPie

AEETriangle

AEEPolygon

IGRAPHICS_SetClip()

返回数据结构列表

AEEClrItem

说明：

该 ENUM 用于指定激活的绘制颜色类型及系统颜色。

定义：

typedef enum
{
CLR_USER_TEXT=1,
CLR_USER_BACKGROUND,
CLR_USER_LINE,
CLR_SYS_TITLE,
CLR_SYS_TITLE_TEXT,
CLR_SYS_ITEM,
CLR_SYS_ITEM_TEXT,
CLR_SYS_ITEM_SEL,
CLR_SYS_ITEM_SEL_TEXT,
CLR_SYS_WIN,
CLR_SYS_FRAME_HI,
CLR_SYS_FRAME_LO,
CLR_SYS_LT_SHADOW,
CLR_SYS_DK_SHADOW,
CLR_SYS_SCROLLBAR,
CLR_SYS_SCROLLBAR_FILL,
CLR_SYS_LAST
} AEEClrItem;

成员：

CLR_USER_TEXT | 激活的文本颜色。
CLR_USER_BACKGROUND | 激活的背景颜色。
CLR_USER_LINE | 激活的线条颜色（边框和其它项）。
CLR_SYS_TITLE | 标题背景。
CLR_SYS_TITLE_TEXT | 标题文本。
CLR_SYS_ITEM | 项目（软键、菜单、按钮）背景。
CLR_SYS_ITEM_TEXT | 项目文本。
CLR_SYS_ITEM_SEL | 已选项背景。
CLR_SYS_ITEM_SEL_TEXT | 已选项文本。
CLR_SYS_WIN | 标准窗口背景。
CLR_SYS_FRAME_HI | 边框突出显示颜色（通常为白色）。
CLR_SYS_FRAME_LO | 边框色块（通常为黑色）。
CLR_SYS_LT_SHADOW | 阴影颜色（通常为浅灰色）。
CLR_SYS_DK_SHADOW | 阴影颜色（通常为深灰色）。
CLR_SYS_SCROLLBAR | 滚动条： 背景。
CLR_SYS_SCROLLBAR_FILL | 滚动条： 填充区域。

备注：

开发者通过 IDISPLAY_SetColor() 只能更改 CLR_USER_TEXT、CLR_USER_BACKGROUND 和 CLR_USER_LINE 的颜色。

另请参阅：

IDISPLAY_SetColor()

返回数据结构列表

AEEDBField

说明：

此结构用于定义记录中的字段， 并用于获取和更新数据库字段。

定义：

typedef structure
{
AEEDBFieldType fType;
AEEDBFieldName fName;
uint16 wDataLen;
void * pBuffer;
} AEEDBField;

成员：

fType | 数据库字段类型（参见文档资料）。
fName | 数据库字段名称（参见文档资料）。
wDataLen | 字段的数据长度（不包括标题）。
pBuffer | 指向包含字段数据的缓冲区的指针。

备注：

无

另请参阅：

AEEDBFieldType

AEEDBFieldName

返回数据结构列表

AEEDBFieldName

说明：

IDBRECORD_NextField() 和 IDBRECORD_GetField() 使用 AEEDBFieldName 返回字段的字段名称。

定义：

typedef enum
{
AEEDBFIELD_NONE,
AEEDBFIELD_FULLNAME,
AEEDBFIELD_LASTNAME,
AEEDBFIELD_FIRSTNAME,
AEEDBFIELD_HOME_PHONE,
AEEDBFIELD_WORK_PHONE,
AEEDBFIELD_MOBILE_PHONE,
AEEDBFIELD_FAX,
AEEDBFIELD_ADDRESS,
AEEDBFIELD_EMAIL,
AEEDBFIELD_URL,
AEEDBFIELD_DATE_TIME,
AEEDBFIELD_CATEGORY,
AEEDBFIELD_ALARM,
AEEDBFIELD_PREF_ID,
AEEDBFIELD_PREF_VER,
AEEDBFIELD_PREF_DATA,
AEEDBFIELD_TITLE,
AEEDBFIELD_TEXT
} AEEDBFieldName;

成员：

AEEDBFIELD_FULLNAME | 包含完整姓名的字段。
AEEDBFIELD_LASTNAME | 包含姓氏的字段。
AEEDBFIELD_FIRSTNAME | 包含名字的字段。
AEEDBFIELD_HOME_PHONE | 包含家庭电话号码的字段。
AEEDBFIELD_WORK_PHONE | 包含工作电话号码的字段。
AEEDBFIELD_MOBILE_PHONE | 包含移动电话号码的字段。
AEEDBFIELD_FAX | 包含传真号码的字段。
AEEDBFIELD_ADDRESS | 包含邮寄地址的字段。
AEEDBFIELD_EMAIL | 包含电子邮件地址的字段。
AEEDBFIELD_URL | 包含 URL 的字段。
AEEDBFIELD_DATE_TIME | 包含日期和时间的字段。
AEEDBFIELD_CATEGORY | 包含类别说明的字段。
AEEDBFIELD_ALARM | 包含警报的字段。
AEEDBFIELD_PREF_ID | 包含首选项 ID 的字段。
AEEDBFIELD_PREF_VER | 包含首选项版本号的字段。
AEEDBFIELD_PREF_DATA | 包含首选项数据（如用户首选项）的字段。
AEEDBFIELD_TITLE | 包含标题的字段。
AEEDBFIELD_TEXT | 包含文本的字段。

备注：

无

另请参阅：

AEEDBField

返回数据结构列表

AEEDBFieldType

说明：

IDBRECORD_GetField() 使用 AEEDBFieldType 返回指定字段的字段类型。

定义：

typedef enum
{
AEEDB_FT_NONE,
AEEDB_FT_BYTE,
AEEDB_FT_WORD,
AEEDB_FT_DWORD,
AEEDB_FT_STRING,
AEEDB_FT_BINARY,
AEEDB_FT_PHONE,
AEEDB_FT_BITMAP,
AEEDB_FT_MAX
} AEEDBFieldType;

成员：

AEEDB_FT_BYTE | 包含 8 位值的字段。
AEEDB_FT_WORD | 包含 16 位值的字段。
AEEDB_FT_DWORD | 包含 32 位值的字段。
AEEDB_FT_STRING | 包含 AECHAR 数组（以 0 结束）的字段。
AEEDB_FT_BINARY | 包含“二进制”值的字段。
AEEDB_FT_PHONE | 包含电话号码的字段。
AEEDB_FT_BITMAP | 包含 BMP 格式位图的字段。

备注：

无

另请参阅：

无

返回数据结构列表

AEEDeviceInfo

说明：

此结构包含 ISHELL_GetDeviceInfo() 中请求的移动设备信息。

.定义：

typedef struct
{
uint16 cxScreen;
uint16 cyScreen;
uint16 cxAltScreen;
uint16 cyAltScreen;
uint16 cxScrollBar;
uint16 wEncoding;
uint16 wMenuTextScroll;
uint16 nColorDepth;
EmptyEnum unused2;
uint32 wMenuImageDelay
uint32 dwRAM;
flg bAltDisplay:1;
flg bFlip:1;
flg bVibrator:1;
flg bExtSpeaker:1;
flg bVR:1;
flg bPosLoc:1;
flg bMIDI:1;
flg bCMX:1;
uint32 dwPromptProps;
uint16 wKeyCloseApp;
uint16 wKeyCloseAllApps;
uint32 dwLang;
uint16 wStructSize;
uint32 dwNetLinger;
uint32 dwSleepDefer;
uint16 wMaxPath;
uint32 dwPlatformID;
} AEEDeviceInfo;

成员：

cxScreen
实际屏幕大小（以像素为单位）
cyScreen
实际屏幕大小（以像素为单位）
cxAltScreen
第二显示屏幕的实际屏幕大小
cyAltScreen
第二显示屏幕的实际屏幕大小
cxScrollBar
标准滚动条的宽度
wEncoding
字符集编码 (AEE_ENC_UNICODE, ....)
nColorDepth
颜色深度（1 表示单色、2 表示灰色等）
dwRAM
已安装的 RAM 总量 (RAM)
bAltDisplay
设备具有备选显示屏幕（寻呼机）
bFlip
设备为翻盖电话
bVibrator
安装了振动器
bExtSpeaker
安装了外部扬声器
bVR
支持语音识别
bPosLoc
支持定位
bMIDI
支持 MIDI 文件格式
bCMX
支持 CMX 音频
dwPromptProps
默认提示属性
wKeyCloseApp
关闭当前应用程序的按键
wKeyCloseAllApps
关闭所有应用程序的按键（默认为 AVK_END）
dwLang
ISO 定义的语言 ID
  • 注意：要使用以下字段，必须在向 GetDeviceInfo 调用传递此结构之前，填充其中的 wStructSize 成员。
dwRAM
已安装的 RAM 总量 (RAM)
bAltDisplay
设备具有备选显示屏幕（寻呼机）
bFlip
设备为翻盖电话
bVibrator
安装了振动器
bExtSpeaker
安装了外部扬声器
bVR
支持语音识别
bPosLoc
支持定位
bMIDI
支持 MIDI 文件格式
bCMX
支持 CMX 音频
dwPromptProps
默认提示属性
wKeyCloseApp
关闭当前应用程序的按键
wKeyCloseAllApps
关闭所有应用程序的按键（默认为 AVK_END）
dwLang
ISO 定义的语言 ID
wStructSize
该结构的大小。 需要填充，以使以下字段有效
dwNetLinger
PPP 延迟时间（毫秒）
dwSleepDefer
手持设备尝试进入睡眠模式之前的时间（毫秒）
wMaxPath
设备支持的最大文件名长度（包括路径名）
dwPlatformID
用于唯一标识设备平台的 ID。

备注：

无

另请参阅：

无

返回数据结构列表

AEEDeviceItem

说明：

指定需要其信息的项目 ID， 用于函数 ISHELL_GetDeviceInfoEx()

定义：

typedef int AEEDeviceItem

成员：

支持的项目如下：

1.名称： AEE_DEVICEITEM_CHIP_ID

说明：

返回标识芯片组 ID 的字符串。 对于 QUALCOMM 芯片集，这些字符串的形式为： MSM3100、MSM3300、MSM5100 等。使用此 ID 调用 ISHELL_GetDeviceInfoEx() 时，将以 AECHAR 形式返回该信息。将此 ID 传递给 ISHELL_GetDeviceInfoEx()，详细情形如下：

int ISHELL_GetDeviceInfoEx (IShell *pIShell, AEEDeviceItem nItem, void *pBuff, int *pnSize);

参数：

pIShell： 指向 IShell 对象的指针。

nItem： 指定 AEE_DEVICEITEM_CHIP_ID。

pBuff： 用于存储 AECHAR 字符串的缓冲区。

pnSize： 输入时，它指定 pBuff 的大小（字节）。 返回时，*pnSize 包含该函数填充 pBuff 的实际大小。 如果 pBuff 为 NULL，或者小于所需大小，则函数将在 *pnSize 中填入实际需要的大小。如果输入时 pnSize 为 NULL，则函数将返回 EBADPARM。

2. 名称： AEE_DEVICEITEM_USER

说明：

OEM 定义条目的起始点。

备注：

无

另请参阅：

ISHELL_GetDeviceInfoEx

返回数据结构列表

AEEDNSClass

说明：

16 位整数，用于存储 DNS“类”的值。 按照 Internet 标准定义并由接受查询的服务器支持的值为有效值。

定义：

typedef int16 AEEDNSQType;

成员：

无

备注：

无

另请参阅：

IDNS_AddQuestion()

返回数据结构列表

AEEDNSItem

说明：

每个 AEEDNSItem 结构可用于说明 DNS 问题，或者说明 DNS 资源记录。

定义：

typedef struct AEEDNSItem {
const byte * pbyDomain;
AEEDNSType nType;
AEEDNSClass nClass;
int32 nTTL;
const byte * pbyData;
int32 cbData;
} AEEDNSItem;

成员：

pbyDomain | “RR/问题”记录的“名称”字段。 它是由指向响应数据的指针给出，并以域名 DNS 格式表示（可能使用头压缩）。 使用 IDNS_ParseDomain() 可获得点分格式表示的字符串（以零结尾）。
nType | “RR/问题”记录的“类型”字段。
nClass | “RR/问题”记录的“类”字段。
nTTL | 仅用于 RR | 32 位 TTL 值。 处理为 32 位有符号整数；请注意，多个记录可能具有不同的 TTL（建议不要执行这种服务器行为）。
pbyData | 仅用于 RR | 指向 RR 记录中 RDATA 字段的指针。 在此内存范围内的任何域名都可以通过 IDNS_ParseDomain() 进行解码。
cbData | 仅用于 RR | RDATA 记录中的字节数。 请注意，如果 pbyData[] 中包含域名，则 cbData 可能远小于结果中以零结尾的域名（由于 DNS 头压缩。）

备注：

无

另请参阅：

无

返回数据结构列表

AEEDNSResponse

说明：

包含 DNS 响应数据。 这些项目直接对应于 DNS 协议规范 (RFC1035) 中说明的字段。

定义：

typedef struct AEEDNSResponse {
uint16 uFlags;
uint16 uReserved;
int16 nQuestions;
int16 nAnswers;
int16 nServers;
int16 nAdditional;
AEEDNSItem * pQuestions;
AEEDNSItem * pAnswers;
AEEDNSItem * pServers;
AEEDNSItem * pAdditional
} AEEDNSResponse;

成员：

uFlags | DNS 消息头的标记字段
uReserved | DNS 消息头的保留字段
nQuestions | 消息中“问题”记录的数量
nAnswers | 消息中“解答”记录的数量
nServers | 消息中“权限”或服务器记录的数量
nAdditional | 消息中“附加”记录的数量
pQuestions | 指向描述“问题”记录的 AEEDNSItem 结构数组的指针。 该数组的大小由 nQuestions 提供。 注意，“问题”记录仅使用 AEEDNSItem 结构中的少数几个字段。 剩余字段保留为零或 NULL。pAnswers、pServers、pAdditional 指针均指向说明“资源记录”的 AEEDNSItem 结构数组。 这些数组的大小分别由 pAnswers、pServers 和 pAdditional 提供。

备注：

无

另请参阅：

IDNS_GetResponse()

返回数据结构列表

AEEDNSResult

说明：

此结构用于保存 INETMGR_GetHostByName() 操作的结果。

定义：

typedef structure
{
int nResult;
INAddr addrs[AEEDNSMAXADDRS];
} AEEDNSResult;

成员：

nResult | 如果是 1..4，则为所获取的地址数量； 否则，为错误代码。 请参阅 INETMGR_GetHostByName()。
addrs[AEEDNSMAXADDRS] | IP 地址。

备注：

无

另请参阅：

INETMGR_GetHostByName()

返回数据结构列表

AEEDNSType

说明：

16 位整数，用于保存 DNS“类型”的值。 按照 Internet 标准定义并由接受查询的服务器支持的值为有效值。

定义：

typedef int16 AEEDNSType;

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEEEllipse

说明：

此结构用于定义椭圆数据类型。

定义：

typedef structure _ellipse
{
int16 cx, cy;
int16 wx;
int16 wy;
} AEEEllipse;

成员：

cx | 椭圆中心的 X 坐标。
cy | 椭圆中心的 Y 坐标。
wx | 椭圆沿 x 轴方向的半轴长度。
wy | 椭圆沿 y 轴方向的半轴长度。

备注：

所有的椭圆都与轴平行， 而长轴可以与 x 轴或 y 轴平行。

另请参阅：

IGRAPHICS_DrawEllipse()

IGRAPHICS_Translate()

返回数据结构列表

AEEFileInfoEx

说明：

AEEFileInfoEx 用于包含与文件相关的扩展信息。

定义：

typedef struct _FileInfoEx
{
int nStructSize;
char attrib;
uint32 dwCreationDate;
uint32 dwSize;
char * pszFile;
int nMaxFile;
AECHAR * pszDescription;
int nDescriptionSize;
AEECLSID * pClasses;
int nClassesSize;
} AEEFileInfoEx;

成员：

nStructSize
结构的大小
attrib
FileAttrib 指定的文件属性
dwCreationDate
文件创建日期
dwSize
文件大小
pszName
ASCIIZ 名称，其中将要填入最大长度为 nMaxName 的文件名
nMaxName
所填名称字段的最大大小
pszDescription
文件的宽字符串说明，大小不超过 nMaxDescription。
nMaxDescription
说明的大小（字节）
pClasses
拥有/使用该文件的 AEECLSID 列表
nMaxClasses
pClasses 列表的大小（字节）

备注：

所有参数均需初始化。 nMaxFile、nDescriptionSize 和 nClassesSize 必须指定指针 nMaxFile、pszDescription 和 pClasses 可容纳的大小（字节）。

另请参阅：

FileInfo

返回数据结构列表

AEEFileUseInfo

说明：

AEEFileUseInfo 用于包含文件的使用信息。

定义：

typedef struct _AEEFileUseInfo
{
uint16 wMaxFiles;
uint16 wFilesUsed;
uint32 dwMaxSpace;
uint32 dwSpaceUsed;
} AEEFileUseInfo;

成员：

wMaxFiles | 该值指定允许模块创建的最大文件数。 其中包含 mod、sig、bar 和任何其它数据文件以及模块中应用程序所创建的后续文件（包括在共享目录中创建的文件）。 有效范围： 7 - 65535
wFilesUsed | 此模块当前使用的文件数
dwMaxSpace | 该值指定允许模块写入的最大字节数。 其中包含模块目录中的所有文件（包括 mod、sig、bar 及其它）以及模块中的应用程序在共享目录中创建的文件的大小。 有效范围： 20480 - 4294967295.
dwSpaceUsed | 此模块迄今为止使用的空间总量

备注：

无

另请参阅：

无

返回数据结构列表

AEEFont

说明：

该 ENUM 用于指定 IDisplay 文本绘制操作中使用的逻辑字体类型。

定义：

typedef enum
{
AEE_FONT_NORMAL=0x8000,
AEE_FONT_BOLD,
AEE_FONT_LARGE,
AEE_FONT_TOTAL
} AEEFont;

成员：

AEE_FONT_NORMAL | 设备支持的正常字体。
AEE_FONT_BOLD | 设备支持的粗字体。
AEE_FONT_LARGE | 设备支持的大字体。
AEE_FONT_TOTAL | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEEFontInfo

说明：

此结构用于说明字体特征。 字符单元高度和基线偏移均为字体属性，这些值在同一字体内不会随字符而变化。

每个字符的图形显示都限定在一个称作字符单元的矩形内。 该单元的高度为字体属性，单元的宽度则可以随字符而变化。 当不透明地绘制文本时，每个字符单元将被绘制到目标位图内大小相同的矩形中，其中的像素被设置为背景颜色或前景颜色。 当以透明方式绘制字符时，将只绘制前景像素，而呈现背景颜色的像素则保持不变。

如果在文本的同一行中使用不同字体，则字体基线对于能否清晰地阅读将非常重要。 基线将字符单元分割成上下行两个区。 下行区域包含字符的下行笔画（延伸至多数字符底部以下的字形部分）以及字符单元底部包含的所有空间。 当在文本的同一行中使用不同字体时，获知字符单元内的基线位置可以使应用程序通过调整字符的垂直位置来对齐基线。

此图显示同一字体的两个相邻字符单元，说明了 nAscent 和 nDescent 与字体基线和字体高度之间的关系：

----------- |
---X------- |
--X-X------ |
-X---X---X- | 上行 = 7
-XXXXX---X- |
-X---X---X- |
-X---X---X-_|_________ 基线
---------X- |
-------XX-- | 下行 = 3
-----------_|__

总高度 = 上行 + 下行 = 7 + 3 = 10

定义：

typedef struct
{
int16 nAscent;
int16 nDescent;
} AEEFontInfo;

成员：

nAscent | 字体在基线以上延伸的最大像素数。
nDescent | 字体在基线以下延伸的最大像素数。

备注：

通过在末尾添加新字段，以后可以扩展该结构。

另请参阅：

IFONT_GetFontInfo()

返回数据结构列表

AEEFrameType

说明：

该 ENUM 用于指定 IDISPLAY_DrawFrame() 函数所支持的各种边框类型。 在使用 IMENUCTL_SetStyle 函数指定菜单项的样式时，也要使用边框类型。

定义：

typedef enum
{
AEE_FT_NONE,
AEE_FT_EMPTY,
AEE_FT_3D_EMPTY,
AEE_FT_RAISED,
AEE_FT_LOWERED,
AEE_FT_BOX,
AEE_FT_INDENT,
AEE_FT_TAB_BOTTOM_SEL,
AEE_FT_TAB_BOTTOM,
AEE_FT_TAB_TOP_SEL,
AEE_FT_TAB_TOP
} AEEFrameType;

成员：

AEE_FT_NONE | 无边框。
AEE_FT_EMPTY | 1 像素的偏移量： 不绘制边框。
AEE_FT_3D_EMPTY | 2 像素的偏移量： 不绘制边框。
AEE_FT_RAISED | 凸起的 2 像素 3d 边框。
AEE_FT_LOWERED | 凹下的 2 像素 3d 边框。
AEE_FT_BOX | 1 像素框。
AEE_FT_INDENT | 凹下的 1 像素 3d 边框。
AEE_FT_TAB_BOTTOM_SEL | 3d 底部选项卡（已选）。
AEE_FT_TAB_BOTTOM | 3d 底部选项卡。
AEE_FT_TAB_TOP_SEL | 3d 顶部选项卡（已选）。
AEE_FT_TAB_TOP | 3d 顶部选项卡。

备注：

无

另请参阅：

AEEItemStyle

返回数据结构列表

AEEGPSConfig

说明：

此结构用于配置该接口提供的 GPS 引擎。

定义：

typedef struct _AEEGPSConfig {
AEEGPSMode mode;
uint16 nFixes;
uint16 nInterval;
AEEGPSOpt optim;
AEEGPSQos qos;
AEEGPSServer server;
} AEEGPSConfig;

成员：

mode
要为此接口配置的操作模式
可能的选项为：
AEEGPS_MODE_ONE_SHOT
仅发出一条位置测定请求。 此选项可能不适用于重复发出位置测定请求的情况。
AEEGPS_MODE_DLOAD_FIRST
此模式适用于重复发出位置测定请求的应用程序，并更倾向于选择从服务器下载初始数据后在移动设备上本地计算结果。
AEEGPS_MODE_TRACK_LOCAL
此模式适用于执行跟踪并且需要频繁快速的位置/速度/海拔高度信息的应用程序。 此外，该模式下为获取位置测定信息只需向网络发送最少量的请求数。
AEEGPS_MODE_TRACK_NETWORK
此模式适用于需要跟踪，并要求从网络获取精确的位置测定信息的应用程序。
AEEGPS_MODE_DEFAULT
设置为 AEEGPS_MOD_DLOAD_FIRST 的默认操作模式
nFixes
使用此接口发出位置测定请求的大致数目。
nInterval
两次定位之间大致的时间间隔（秒）。
optim
此接口所需的优化。
可能的取值为：
  • AEEGPS_OPT_SPEED： 优化速度
    AEEGPS_OPT_ACCURACY： 优化精确度。
    AEEGPS_OPT_DEFAULT： 默认值。 设置为速度优化。
qos
服务质量值，有效值介于 1-255 之间，255 提供最佳服务质量。 特定的移动设备可能会忽略此选项。
server
服务器配置将指定服务器类型和配置。 可能的服务器类型为：
  • AEEGPS_SERVER_DEFAULT
  • AEEGPS_SERVER_IP
  • AEEGPS_SERVER_DBURST
如果服务器类型为 AEEGPS_SERVER_IP，则必须指定位置测定服务器的 IP 地址和端口。

备注：

无

另请参阅：

无

返回数据结构列表

AEEGPSInfo

说明：

此结构用于从系统获取基于 GPS 的定位信息。 这些参数均按照 TIA/EIA IS-801 标准返回。

定义：

typedef struct _AEEGPSInfo {
uint32 dwTimeStamp;
uint32 status;
int32 dwLat;
int32 dwLon;
int16 wAltitude;
uint16 wHeading;
uint16 wVelocityHor;
int8 bVelocityVer;
AEEGPSAccuracy accuracy;
uint16 fValid;
uint8 bHorUnc;
uint8 bHorUncAngle;
uint8 bHorUncPerp;
uint16 wVerUnc;
} AEEGPSInfo;

成员：

dwTimeStamp： 此次度量的时间（自 1980 年 6 月 1 日至今，以秒计）

status： 响应状态

dwLat： 纬度，180/2^25 度、WGS-84 椭球

dwLon： 经度，360/2^26 度、WGS-84 椭球

wAltitude： 海拔高度，米、WGS-84 椭球

wHeading： 航向，360/2^10 度

wVelocityHor： 水平速度，0.25 米/秒

bVelocityVer： 水平速度，0.25 米/秒

accuracy： 数据精确度。

fValid： 指示结构中有效字段的标记。

bHorUnc： 水平误差

bHorUncAngle： 水平角度误差

bHorUncPerp： 水平正交误差

bVerUnc： 垂直误差

备注：

fValid 指示在 AEEGPSInfo 结构中设置的字段。 以下

为可用标记。

AEEGPS_VALID_LAT： 有效纬度

AEEGPS_VALID_LON： 有效经度

AEEGPS_VALID_ALT： 有效海拔高度

AEEGPS_VALID_HEAD： 有效航向

AEEGPS_VALID_HVEL： 有效水平速度

AEEGPS_VALID_VVEL： 有效垂直速度

AEEGPS_VALID_HUNC： 有效水平误差

AEEGPS_VALID_AUNC： 有效水平角度误差

AEEGPS_VALID_PUNC： 有效水平误差（正交）

精确度可指定为 6 级（从 AEEGPS_ACCURACY_LEVEL1 开始）

另请参阅：

无

返回数据结构列表

AEEGPSIPServer

说明：

此结构用于指定 IP 服务器。 服务器类型指定为 AEEGPS_SERVER_IP 时使用该结构。

定义：

typedef struct _AEEGPSIPServer {
INAddr addr;
INPort port;
uint16 reserved;
} AEEGPSIPServer;

成员：

addr | 服务器 32 位 IP 地址（主机字节顺序）
port | 要连接的端口。

备注：

无

另请参阅：

无

返回数据结构列表

AEEGPSMode

说明：

此结构用于指定设备上 GPS 系统的操作模式。

定义：

typedef uint16 AEEGPSMode;

定义：

AEEGPS_MODE_ONE_SHOT | 一次性请求。 无需从 PDE 下载数据进行后续定位。
AEEGPS_MODE_DLOAD_FIRST | 首次从 PDE 获取定位和卫星数据。 后续定位将在手持设备上进行计算。 这将使网络使用量降至最低。 此选项为默认的 AEEGPS_MODE_DEFAULT 选项
AEEGPS_MODE_TRACK_LOCAL | 利用已下载的卫星数据（星历表数据和年历）跟踪， 而不使用网络进行跟踪。
AEEGPS_MODE_TRACK_NETWORK | 使用网络跟踪（IP 或数据突发）。

备注：

无

另请参阅：

无

返回数据结构列表

AEEGPSOpt

说明：

此数据类型用于指定位置测定子系统所需的优化。

定义：

typedef uint8 AEEGPSOpt;

定义：

AEEGPS_OPT_SPEED
优化 GPS 定位时间。
AEEGPS_OPT_ACCURACY
优化 GPS 定位精确度。 此选项可能需要较长时间和网络连接或较多的数据突发消息。
AEEGPS_OPT_DEFAULT
设置为 AEEGPS_OPT_SPEED。

备注：

无

另请参阅：

无

返回数据结构列表

AEEGPSServer

说明：

此结构指定将用于 GPS 位置测定的服务器类型和规格。

定义：

typedef struct _AEEGPSServer{
AEEGPSSvrType svrType;
union {
AEEGPSIPServer ipsvr;
} svr;
} AEEGPSServer;

成员：

svr
要使用的服务器规格。

备注：

此结构包含联合结构以支持未来的服务器类型。

另请参阅：

无

返回数据结构列表

AEEGPSSvrType

说明：

此数据类型用于指定 GPS 服务将使用的服务器类型。

定义：

typedef uint32 AEEGPSSvrType;

定义：

AEEGPS_SERVER_DEFAULT | 使用运营商或 OEM 指定的默认服务器。
AEEGPS_SERVER_IP | 使用基于 IP 的 GPS 服务器。 （另请参阅 AEEGPSIPServer）
AEEGPS_OPT_DBURST | 向（或从）GPS 服务器进行传输时使用数据突发消息。

备注：

无

另请参阅：

无

返回数据结构列表

AEEHANDLER

说明：

此数据类型为函数指针，用于指定 BREW 中事件处理函数的原型。 IApplet 接口由具有此原型的成员函数组成

定义：

typedef boolean (*AEEHANDLER)
(
void * pData,
AEEEvent evt,
uint16 wParam,
uint32 lParam
);

成员：

pData | 接口或数据指针
evt | 事件代码
wParam | 事件特定的参数
dwParam | 事件特定的参数

备注：

无

另请参阅：

无

返回数据结构列表

AEEHandlerType

注意：建议不使用此数据结构。

说明：

之前使用的 ENUM，用于指定 ISHELL_RegisterHandler()、ISHELL_GetHandler() 等函数中的处理程序类型。

定义：

typedef AEEHandlerType enum
{
HTYPE_VIEWER,
HTYPE_SOUND,
HTYPE_BROWSE
} AEEHandlerType;

成员：

HTYPE_VIEWER | 指定提供图像查看服务的 IViewer 类处理程序（对于不合格的 image/\* mimetype）。
HTYPE_SOUND | 指定提供声音播放服务的 ISoundPlayer 类处理程序（对于不合格的 snd/\* mimetype）。
HTYPE_BROWSE | 指定支持资源类型（如 http 和 mailto）或文件扩展名（如 .gif 和 .htm）的 IApplet 类处理程序。 HTYPE_BROWSE 支持最少，应避免使用。

备注：

建议不要使用此类型；有关应使用类型的信息，请参阅 AEECLSID 列表。

另请参阅：

无

返回数据结构列表

AEEImageInfo

说明：

此结构用于获取图像的相关信息。

定义：

typedef structure _AEEImageInfo
{
uint16 cx;
uint16 cy;
uint16 nColors;
boolean bAnimated;
uint16 cxFrame;
} AEEImageInfo;

成员：

cx | 图像的宽度（以像素为单位）。
cy | 图像的高度（以像素为单位）。
nColors | 图像中的颜色数目。
bAnimated | TRUE，如果图像包含动画。
cxFrame | 如果将图像分成图像帧，该元素指示每帧的宽度。

备注：

无

另请参阅：

PFNIMAGEINFO

返回数据结构列表

AEEItemStyle

说明：

此结构用于指定项目样式。

定义：

typedef structure
{
AEEFrameType ft;
uint16 xOffset;
uint16 yOffset;
AEERasterOp roImage;
} AEEItemStyle;

成员：

ft | 项目的边框类型。
xOffset | 项目内 X 方向的填充（不包括边框大小）。
yOffset | 项目内 Y 方向的填充（不包括边框大小）。
roImage | 项目内绘制图像的光栅操作。

备注：

无

另请参阅：

AEEFrameType

AEERasterOp

返回数据结构列表

AEEItemType

说明：

该 ENUM 用于指定使用 ISHELL_GetItemStyle() 请求其样式的项目类型。

定义：

typedef enum
{
AEE_IT_MENU,
AEE_IT_SOFTKEY,
AEE_IT_ICONVIEW
} AEEItemType;

成员：

AEE_IT_MENU | 菜单项类型。
AEE_IT_SOFTKEY | 软键项目类型。
AEE_IT_ICONVIEW | 图标视图项目类型。

备注：

无

另请参阅：

无

返回数据结构列表

AEELicenseType

说明：

该 ENUM 用于指定由 ILICENSE_GetInfo() 返回的许可类型。

定义：

typedef enum
{
LT_NONE,
LT_USES,
LT_DATE,
LT_DAYS,
LT_MINUTES_OF_USE,
LT_MAX
} AEELicenseType;

成员：

LT_NONE | 该模块没有期限。
LT_USES | 使用计数器。
LT_DATE | 到期日期。
LT_DAYS | 到期日期。
LT_MINUTES_OF_USE | 剩余的分钟数。
LT_MAX/ | 未使用。

备注：

无

另请参阅：

ILICENSE_GetInfo()

返回数据结构列表

AEELine

说明：

此结构用于定义线段数据类型。

定义：

typedef structure _line
{
int16 sx, sy;
int16 ex, ey;
} AEELine;

成员：

sx | 线段起点的 X 坐标。
sy | 线段起点的 Y 坐标。
ex | 线段终点的 X 坐标。
ey | 线段终点的 Y 坐标。

备注：

在数学上直线是无限长的，因此 AEELine 定义的是一条从 (sx, sy) 至 (ex, ey) 的线段，而不是数学直线。 线段包括两个端点。

另请参阅：

IGRAPHICS_DrawLine()

返回数据结构列表

AEEMatrixTransform

说明：

此结构说明用于执行复杂转换的 2X2 矩阵。

定义：

typedef struct {
int16 A;
int16 B;
int16 C;
int16 D;
} AEETransformMatrix;

成员：

A, B, C, D： 具有 8 位整数部分和 8 位小数部分的定点值。 （例如，2.5 代表 2.5 * 256 或 640。） 它构成的 2x2 矩阵如下

[ A B
  C D ]

备注：

一些示例转换

2.5 倍放大： A = 640、B = 0、

C = 0、D = 640。

旋转： A = 256 * cos（角度）、B = 256 * sin（角度）、

C = 256 * -sin（角度）、D = 256 * cos（角度）。

注意： 上述值已经转换为定点值。

另请参阅：

ITRANSFORM_TransformBltComplex()

返回数据结构列表

AEEMediaCmdNotify

说明：

此结构包含 IMedia 通过已注册小程序回调所返回事件的相关信息。

定义：

typedef structure
{
AEECLSID clsMedia;
IMedia * pIMedia;
int nCmd;
int nSubCmd;
int nStatus;
void * pCmdData;
uint32 dwSize;
} AEEMediaCmdNotify;

成员：

clsMedia | IMedia 具体类的 CLSID。
pIMedia | 指向 IMedia 的指针。
nCmd | 命令代码。
nSubCmd | 子命令代码（如果有，否则为 0（零））。
nStatus | 状态代码。
pCmdData | 包含以上所列值之一。
dwSize | pCmdData 的大小。

备注：

下表给出了包含命令、子命令、状态和上下文相关数据的可能事件：

nCmd | nSubCmd | nStatus | pData [可选]
MM_CMD_SETMEDIAPARM | MM_PARM_XXX （参见 IMEDIA_SetMediaParm()） | MM_STATUS_DONE | <取决于参数>
 |  | MM_STATUS_ABORT |
MM_CMD_GETMEDIAPARM | MM_PARM_XXX （参见 IMEDIA_GetMediaParm()） | MM_STATUS_DONE | <取决于参数>
 |  | MM_STATUS_ABORT |
MM_CMD_PLAY | 0 | MM_STATUS_START |
 |  | MM_STATUS_DONE |
 |  | MM_STATUS_ABORT |
 |  | MM_STATUS_MEDIA_SPEC | [指向 MediaSpec 的指针]
 |  | MM_STATUS_TICK_UPDATE |
 |  | MM_STATUS_DATA_IO_DELAY | 已用时间 （毫秒）
 |  | MM_STATUS_SEEK | [已用时间 （毫秒）]
 |  | MM_STATUS_SEEK_FAIL |
 |  | MM_STATUS_PAUSE | 已用时间 （毫秒）
 |  | MM_STATUS_PAUSE_FAIL |
 |  | MM_STATUS_RESUME | 已用时间 （毫秒）
 |  | MM_STATUS_RESUME_FAIL |
 |  | MM_STATUS_REPEAT | [已用时间 （毫秒）]
MM_CMD_RECORD | 0 | MM_STATUS_START |
 |  | MM_STATUS_DONE |
 |  | MM_STATUS_ABORT |
 |  | MM_STATUS_MEDIA_SPEC | [指向 MediaSpec 的指针]
 |  | MM_STATUS_TICK_UPDATE |
 |  | MM_STATUS_DATA_IO_DELAY | [已用时间 （毫秒）]
 |  | MM_STATUS_SEEK | [已用时间 （毫秒）]
 |  | MM_STATUS_SEEK_FAIL |
 |  | MM_STATUS_PAUSE | [已用时间 （毫秒）]
 |  | MM_STATUS_PAUSE_FAIL |
 |  | MM_STATUS_RESUME | [已用时间 （毫秒）]
 |  | MM_STATUS_RESUME_FAIL |
 |  | MM_STATUS_SPACE_WARNING |
 |  | MM_STATUS_SPACE_ERROR |
MM_CMD_GETTOTALTIME | 0 | MM_STATUS_DONE | 总时间（毫秒）
 |  | MM_STATUS_ABORT |

另请参阅：

PFNMEDIANOTIFY

IMEDIA_SetMediaParm()

IMEDIA_GetMediaParm()

IMEDIA_Play()

IMEDIA_Record()

IMEDIA_GetTotalTime()

返回数据结构列表

AEEMediaData

说明：

此结构用于定义与媒体数据相关联的流类型和上下文相关数据。

定义：

typedef structure
{
AEECLSID clsData;
void * pData;
uint32 dwSize;
} AEEMediaData;

成员：

clsData | 流类型。
pData | 上下文相关数据。
dwSize | 上下文相关数据。

备注：

下表给出了预定义流类型上下文相关数据的详细信息。 “读/写”表示“播放/记录”。

clsData | 模式 | pData | dwSize
MMD_FILE_NAME | 读/写 | 文件名 | 0
MMD_BUFFER | 读/写 | 缓冲区指针 | 数据大小或 0
MMD_RT_IASTREAM | 只读 | IAStream * | 数据大小或 0
MMD_RT_ISOURCE | 只读 | ISource * | 数据大小或 0

对于播放，可将 cls 设置为任何基于 ISource 类（其 pData 设置为对应的接口指针）的 CLSID。

对于记录，只允许使用 MMD_FILE_NAME/MMD_BUFFER 类型。 现有文件名或内存缓冲区将被覆盖。

另请参阅：

无

返回数据结构列表

AEEMediaMIDISpec

说明：

MIDI 格式规范说明。

定义：

typedef struct AEEMediaMIDISpec
{
byte nFormat;
uint16 nTracks;
int16 nDivision;
} AEEMediaMIDISpec;

成员：

nFormat
SMF 格式 0、1 或 2
nTracks
SMF 中的跟踪数目
nDivision
定时信息

备注：

此结构由处理 MIDI 格式的 IMedia 对象在 MM_MEDIA_SPEC 回调中任意返回。

另请参阅：

IMEDIA_Play()

返回数据结构列表

AEEMediaMP3Spec

说明：

MP3 格式规范说明。

定义：

typedef struct AEEMediaMP3Spec
{
int nVersion;
byte nLayer;
boolean bCRCFlag;
uint16 wBitRate;
uint32 dwSampleRate;
byte nChannel;
byte nExtension;
boolean bCopyrightFlag;
boolean bOriginalFlag;
byte nEmphasis;
char szTitle[MM_MP3_ID3_TAG_LENGTH];
char szArtist[MM_MP3_ID3_TAG_LENGTH];
char szAlbum[MM_MP3_ID3_TAG_LENGTH];
char szYear[4];
char szComment[MM_MP3_ID3_TAG_LENGTH];
byte nGenre;
} AEEMediaMP3Spec;

成员：

nVersion
MPEG 版本
nLayer
MPEG 层压缩： 1、2 或 3
bCRCFlag
TRUE（如果使用 CRC 保护）
wBitRate
比特率 [千位]
dwSampleRate
采样率 [千位]
nChannel
声道
nExtension
仅用于 JOINT_STEREO
bCopyrightFlag
TRUE（如果拥有版权）
bOriginalFlag
TRUE（如果为原版）
nEmphasis
音频加强
szTitle
歌曲标题
szArtist
歌曲演绎者
szAlbum
歌曲专辑
szYear
发行专辑的年份
szComment
文本评论
nGenre
ID3 类型标签

备注：

此结构由处理 MP3 格式 IMedia 对象在 MM_MEDIA_SPEC 回调中任意返回。

另请参阅：

IMEDIA_Play()

返回数据结构列表

AEEMediaSeek

说明：

此枚举用于指定 IMEDIA_Seek() API 中的搜索参考。

定义：

typedef enum AEEMediaSeek
{
MM_SEEK_START = 0,
MM_SEEK_END,
MM_SEEK_CURRENT
} AEEMediaSeek;

成员：

MM_SEEK_START： 从媒体的开头搜索

MM_SEEK_END： 从媒体的结尾搜索

MM_SEEK_CURRENT： 从媒体的当前位置搜索

备注：

IMEDIA_Rewind() 和 IMEDIA_FastForward() 使用 MM_SEEK_CURRENT。

另请参阅：

IMEDIA_Seek()

IMEDIA_Rewind()

IMEDIA_FastForward()

返回数据结构列表

AEEMenuColors

说明：

AEEMenuColors 用于指定各种菜单控件对象元素的基本颜色值。

定义：

typedef structure
{
uint16 wMask;
RGBVAL cBack;
RGBVAL cText;
RGBVAL cSelBack;
RGBVAL cSelText;
RGBVAL cFrame;
RGBVAL cScrollbar;
RGBVAL cScrollbarFill;
RGBVAL cTitle;
RGBVAL cTitleText;
} AEEMenuColors;

成员：

wMask | 在该结构中需要注意的位掩码。
cBack | 未选项的背景色。
cText | 未选项和箭头的文本颜色。
cSelBack | 已选项的背景色。
cSelText | 已选项的文本颜色。
cFrame | 单边框的颜色。
cScrollbar | 滚动条边框的颜色。
cScrollbarFill | 滚动条填充颜色。
cTitle | 标题文本的背景色。
cTitleText | 标题文本的颜色。

备注：

无

另请参阅：

RGBVAL

IMENUCTL_SetColors()

AEEMenuColorsMask

返回数据结构列表

AEEMenuColorsMask

说明：

掩码集，用于指示需要更改其颜色的项目。

定义：

MC_BACK | 未选项目背景。
MC_TEXT | 未选项目文本。
MC_SEL_BACK | 已选项目背景。
MC_SEL_TEXT | 已选项目文本。
MC_FRAME | 单边框的颜色。
MC_SCROLLBAR | 滚动条边框的颜色。
MC_SCROLLBAR_FILL | 滚动条填充颜色。
MC_TITLE | 标题背景色。 该掩码仅支持用于列表控件。
MC_TITLE_TEXT | 标题文本颜色。 该掩码仅支持用于列表控件。

成员：

无

备注：

无

另请参阅：

AEEMenuColors

返回数据结构列表

AEEMenuSortType

说明：

AEEMenuSortType 用于指定排序类型。

定义：

typedef enum
{
MCS_CUSTOM,
MCS_NAME_DESCENDING,
MCS_NAME_ASCENDING,
MCS_PARAM_DESCENDING,
MCS_PARAM_ASCENDING
} AEEMenuSortType;

成员：

MCS_CUSTOM | 自定义排序。
MCS_NAME_DESCENDING | 名称降序。
MCS_NAME_ASCENDING | 名称升序。
MCS_PARAM_DESCENDING | 用户数据降序。
MCS_PARAM_ASCENDING | 用户数据升序。

备注：

无。

另请参阅：

PFNMENUSORTCOMPARE

IMENUCTL_Sort()

返回数据结构列表

AEENetStats

说明：

此结构用于说明网络连接的状态（PPP 连接状态）。

定义：

typedef structure
{
uint32 dwOpenTime;
uint32 dwActiveTime;
uint32 dwBytes;
uint32 dwRate;
uint32 dwTotalOpenTime;
uint32 dwTotalActiveTime;
uint32 dwTotalBytes;
uint32 dwTotalRate;
} AEENetStats;

成员：

dwOpenTime | 建立 PPP 连接以来的时间（秒）。
dwActiveTime | PPP 连接已激活的时间（秒）。
dwBytes | 连接时发送的总字节数。
dwRate | 传输速度（字节/秒）。
dwTotalOpenTime | 所有打开的 PPP 会话的时间总量（秒）。
dwTotalActiveTime | 所有激活的 PPP 会话的时间总量（秒）。
dwTotalBytes | 发送的总字节数（所有连接）。
dwTotalRate | 速率总和（所有连接）。

备注：

无

另请参阅：

无

返回数据结构列表

AEENotify

说明：

向应用程序发送 EVT_NOTIFY 事件时，将指向该结构的指针作为 dwParam 传递。 应用程序接收此事件作为所注册通知的一部分。

定义：

typedef structure
{
AEECLSID cls;
INotifier * pNotifier;
uint32 dwMask;
void * pData;
AEENotifyStatus st;
} AEENotify;

成员：

cls | 通知程序类。
pNotifier | 发布通知的通知程序对象。
dwMask | 发生的位掩码。
pData | 通知特定数据。
st | 指示 IShell，应用程序是否已处理通知。

备注：

无

另请参阅：

ISHELL_RegisterNotify()

ISHELL_Notify()

AEENotifyStatus

AEECLSID 列表

返回数据结构列表

AEENotifyStatus

说明：

此枚举类型用于定义由接收通知的小程序返回给外壳的通知状态值。 通过设置与此 EVT_NOTIFY 事件一起传递的 AEENotify 结构的 st 成员，小程序返回其处理通知的状态。

定义：

typedef enum
{
NSTAT_PROCESSED,
NSTAT_IGNORED,
NSTAT_STOP
} AEENotifyStatus;

成员：

NSTAT_PROCESSED | 小程序已成功处理通知。
NSTAT_IGNORED | 小程序已忽略通知。
NSTAT_STOP | 小程序已处理通知，但该通知无法发送给已注册接收该事件通知的其它任何小程序。

备注：

无

另请参阅：

ISHELL_RegisterNotify()

ISHELL_Notify()

ISHELL_RegisterNotify() (请参阅《BREW API 参考资料指南》。)

ISHELL_Notify() (请参阅《BREW API 参考资料指南》。)

AEENotify

返回数据结构列表

AEEPaintMode

说明：

该枚举类型指定绘制的光栅操作类型。

定义：

typedef enum {AEE_PAINT_COPY, AEE_PAINT_XOR} AEEPaintMode;

成员：

AEE_PAINT_COPY | 复制光栅操作。
AEE_PAINT_XOR | “异或”光栅操作。

备注：

如果着色模式为 AEE_PAINT_COPY，新的内容将覆盖原有显示缓冲区中的内容。
如果着色模式为 AEE_PAINT_XOR，新旧内容的“异或”结果将写入到显示缓冲区中。 默认情况下，IGraphics 的着色模式为 AEE_PAINT_COPY。 通过调用 IGRAPHICS_SetPaintMode()，程序可更改着色模式。

另请参阅：

IGRAPHICS_SetPaintMode()

返回数据结构列表

AEEPie

说明：

此结构用于定义饼图数据类型。

定义：

typedef structure _pie
{
int16 cx, cy;
int16 r;
int16 startAngle;
int16 arcAngle;
} AEEPie;

成员：

cx | 参考圆圆心的 X 坐标。
cy | 参考圆圆心的 Y 坐标。
r | 参考圆的半径。
startAngle | 圆弧的起始角度（度）。
arcAngle | 圆弧角度（度）。

备注：

该数据结构中的参数与 AEEArc 中的一致， 因而在必要时可以方便地将 AEEPie 类型转换成 AEEArc。

另请参阅：

AEEArc

IGRAPHICS_DrawPie()

IGRAPHICS_Translate()

返回数据结构列表

AEEPoint

说明：

此结构用于定义点数据类型。

定义：

typedef structure _point {int16 x, y;} AEEPoint;

成员：

x | X 坐标。
y | Y 坐标。

备注：

无

另请参阅：

IGRAPHICS_DrawPoint()

返回数据结构列表

AEEPolygon

说明：

此结构用于定义多边形数据类型。

定义：

typedef structure _polygon
{
int16 len;
AEEPoint * points;
} AEEPolygon;

成员：

len | 多边形的顶点数。
points | 多边形的顶点数组。

备注：

无

另请参阅：

AEEPoint

IGRAPHICS_DrawPolygon()

IGRAPHICS_Translate()

返回数据结构列表

AEEPolyline

说明：

此结构用于定义折线数据类型。 折线是一系列连接的线段。

定义：

typedef structure _polyline
{
int16 len;
AEEPoint * points;
} AEEPolyline;

成员：

len | 折线的点数。
points | 折线中的点数组。

备注：

该数据类型具有与 AEEPolygon 完全一致的结构， 从而可以在 AEEPolyline 和 AEEPolygon 之间进行方便的转换。

另请参阅：

AEEPoint

IGRAPHICS_DrawPolyline()

IGRAPHICS_Translate()

返回数据结构列表

AEEPosAccuracy

说明：

该数据结构用于说明“定位信息精确度”。

定义：

typedef enum
{
AEE_ACCURACY_LOW,
AEE_ACCURACY_MED,
AEE_ACCURACY_HIGH
} AEEPosAccuracy;

成员：

无

备注：

该定位信息精确度与实现 ISHELL_GetPosition() 请求所需的时间直接相关。

另请参阅：

ISHELL_GetPosition()

返回数据结构列表

AEEPositionInfo

说明：

该数据结构用于说明定位信息。

定义：

typedef structure
{
int32 dwLat;
int32 dwLon;
uint32dwTimeStamp;
} AEEPositionInfo;

成员：

dwLat | 纬度，180/2^25 度、WGS-84 椭球。
dwLon | 经度，360/2^26 度、WGS-84 椭球。
dwTimeStamp | 时间戳，自 1980 年 6 月 1 日至今的秒数。

备注：

无。

另请参阅：

ISHELL_GetPosition()

返回数据结构列表

AEEPriceType

说明：

此枚举用于说明 ILICENSE_GetPurchaseInfo() 返回的价格类型。

定义：

typedef enum
{
PT_NONE,
PT_DEMO,
PT_PURCHASE,
PT_SUBSCRIPTION,
PT_UPGRADE,
PT_MAX
} AEEPriceType;

成员：

PT_NONE | ILicence_GetPurchace() 失败。
PT_DEMO | 免费演示。
PT_PURCHASE | 购买价格。
PT_SUBSCRIPTION | 订购价格。
PT_UPGRADE | 升级价格。
PT_MAX | 未使用。

备注：

无

另请参阅：

ILICENSE_GetPurchaseInfo()

返回数据结构列表

AEEPromptInfo

说明：

此结构用于指定 ISHELL_Prompt() 函数使用的提示信息。

定义：

typedef structure
{
const char * pszRes;
const AECHAR * pTitle;
const AECHAR * pText;
uint16 wTitleID;
uint16 wTextID;
uint16 wDefBtn;
const uint16 * pBtnIDs;
uint32 dwProps;
AEEFont fntTitle;
AEEFont fntText;
uint32 dwTimeout;
} AEEPromptInfo;

成员：

pszRes | 用于提示标题和文本信息的资源文件名。
pTitle | 如果未指定 pszRes，则为包含提示标题的宽字符串指针。
pText | 如果未指定 pszRes，则为包含提示文本的宽字符串指针。
wTitleID | 如果已指定 pszRes，则为资源文件中标题字符串的 ID。
wTextID | 如果已指定 pszRes，则为资源文件中文本字符串的 ID。
wDefBtn | 默认的 ID。
pBtnIDs | 指向按钮 ID 数组的指针。 该数组必须以 NULL 结尾
dwProps | 提示的属性（参见 IStatic 接口属性）。
fntTitle | 标题字体。
fntText | 文本字体。
dwTimeout | 提示的超时值。 如果设置为 0（零），则提示没有超时值。

备注：

如果 pszRes、pTitle 和 pText 不为 NULL，则从资源文件中读取提示标题和文本。

另请参阅：

AEEFont

ISHELL_Prompt()

返回数据结构列表

AEERasterOp

说明：

该 ENUM 指定光栅操作，用于位图的位块传输以及使用 IImage 接口函数在屏幕上绘制图像。

定义：

typedef enum
{
AEE_RO_OR,
AEE_RO_XOR,
AEE_RO_COPY,
AEE_RO_NOT,
AEE_RO_MASK,
AEE_RO_MERGENOT,
AEE_RO_MASKNOT,
AEE_RO_TRANSPARENT,
AEE_RO_TOTAL
} AEERasterOp;

成员：

注意：

建议不要使用 AEE_RO_MASK，而使用 AEE_RO_OLDTRANSPARENT。

建议不要使用 AEE_RO_MASKNOT，而使用 AEE_RO_ANDNOT。

AEE_RO_TOTAL 本身并不是光栅操作，但十分重要，因而也列于此处。

AEE_RO_OR | SRC .OR. DST*。
AEE_RO_XOR | SRC .XOR. DST*。
AEE_RO_COPY | DST = SRC*。
AEE_RO_NOT | DST = (!SRC)*。
AEE_RO_OLDTRANSPARENT | 与 AEE_RO_TRANSPARENT 相同。 单色模式下，等于 DST .AND. SRC*。
AEE_RO_MERGENOT | DST .OR. (!SRC)。
AEE_RO_ANDNOT | DST .AND. (!SRC)。
AEE_RO_TRANSPARENT | 特定颜色的 SRC* 像素是透明的意味着可透过该像素看到对应的 DST* 像素： 对于单色设备，该颜色为 RGB_MASK_MONO，白色。 对于灰度设备，该颜色为 RGB_MASK_GREY，白色。 对于彩色设备，该颜色为 RGB_MASK_COLOR，紫色。
AEE_RO_TOTAL | 光栅操作的总数
* 其中 SRC 是源位图缓冲区，DST 为目标位图缓冲区。

备注：

无

另请参阅：

无

返回数据结构列表

AEERect

说明：

AEERect 用于定义不同的“显示”、“图形”、“文本控件”和其它助手函数使用的矩形。

定义：

typedef structure
{
int16 x, y;
int16 dx, dy;
} AEERect;

成员：

x | 矩形起始点（左上角）的水平坐标。
y | 矩形起始点（左上角）的垂直坐标。
dx | 矩形的宽度（以像素为单位）。
dy | 矩形的高度（以像素为单位）。

备注：

无

另请参阅：

无

返回数据结构列表

AEEResBlob

说明：

此二进制数据资源结构返回于 ISHELL_LoadResDataEx()。

定义：

typedef structure AEEResBlob
{
byte bDataOffset;
byte bZero;
char szMimeType[1];
} AEEResBlob;

成员：

bDataOffset | Blob 内实际数据开始处。
bZero | 始终为零，它在 1.x BREW 中用于补白。
szMimeType[1] | 以 Null 结尾的 mimetype 字符串（不只是 [1]）；其长度可达 249 个字符。

备注：

使用宏 RESBLOB_DATA() 可以获取指向实际数据的指针，它开始于以 NULL 结尾的 MIME 类型之后。只有 RESTYPE_IMAGE 或 RESTYPE_BINARY 才返回这种数据类型。

另请参阅：

ISHELL_LoadResDataEx()

返回数据结构列表

AEERingerCat

说明：

此数据结构包含有关振铃器类别的信息。

定义：

typedef structure _AEERingerCat
{
AEERingerCatID id;
AEERingerID idRinger;
AECHAR szName[MAX_RINGER_CATEGORY];
} AEERingerCat;

成员：

id | 稍后调用时使用的类别 ID。
idRinger | 默认振铃器类别的 ID。
szName | 类别的宽字符串名称。

备注：

无

另请参阅：

AEERingerID

返回数据结构列表

AEERingerCatID

说明：

振铃器类别标识符。

定义：

无

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEERingerEvent

说明：

AEERingerEvent 用于指定 IRingerMgr 接口发送的不同通知。 这些通知将由使用 IRINGERMGR_RegisterNotify() 注册的通知函数发送。

定义：

typedef enum
{
ARE_NONE,
ARE_PLAY,
ARE_CREATE,
ARE_WRITE
} AEERingerEvent;

成员：

ARE_NONE | 没有发出通知。
ARE_PLAY | 播放完成或调用 IRINGERMGR_Stop() 时发出。
ARE_CREATE | 完成创建振铃器或发生错误时发出。
ARE_WRITE | 每次写入振铃器文件时发出。

备注：

无

另请参阅：

PFNRINGEREVENT

IRINGERMGR_RegisterNotify()

返回数据结构列表

AEERingerID

说明：

振铃器标识符。

定义：

无

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

AEERingerInfo

说明：

此数据结构包含有关振铃器的信息。

定义：

typedef struct _AEERingerInfo
{
AEERingerID id;
AEESoundPlayerFile format;
char szFile[MAX_FILE_NAME];
AECHAR szName[MAX_RINGER_NAME];
} AEERingerInfo;

成员：

id | 振铃器 ID。
format | 振铃器声音格式。
szFile[MAX_FILE_NAME] | 振铃器文件的完整路径。 如果只读，则为 0（零）字符串。
szName[MAX_RINGER_NAME] | 振铃器名称。

备注：

无

另请参阅：

AEERingerID

AEESoundPlayerFile

返回数据结构列表

AEERLP3Cfg

说明：

一些设备的网络层可能会在 PPP 下使用 RLP3，因而可能需要进行配置。 该数据结构即用于表示 RLP3 配置。 该结构可作为 pOptVal 参数传递到 INETMGR_GetOpt()/INETMGR_SetOpt()。

定义：

typedef struct AEERLP3Cfg
{
byte ucFwdNakRounds;
byte aucFwdNaksPerRound[3];
byte ucRevNakRounds;
byte aucRevNaksPerRound[3];
}AEERLP3Cfg;

成员：

ucFwdNakRounds | 向前转发 NAK 的轮数（最大为 3）
aucFwdNaksPerRound | 每轮向前转发的 NAK
ucRevNakRounds | 逆向转发 NAK 的轮数（最大为 3）
aucRevNaksPerRound | 每轮逆向转发的 NAK

备注：

无

另请参阅：

INETMGR_GetOpt()

INETMGR_SetOpt()

返回数据结构列表

AEESectorInfo

说明：

此结构用于从系统获取基于扇区的定位信息。

定义：

typedef struct _AEESectorInfo
{
uint16 wSysID;
uint16 wNetID;
uint16 wBaseID;
uint16 wBaseClass;
uint16 wBestPN;
uint16 wBestPN;
uint16 wPacketZoneID;
uint16 wMobileCountryCode;
}AEESectorInfo;

成员：

wSysID
系统标识
wNetID
网络标识
wBaseStationID
基站标识
wBaseStationClass
基站类
wBestPN
最佳导航
wPacketZoneID
数据包数据服务区标识符
wMobileCountryCode
移动国家/地区代码

备注：

无

另请参阅：

IPOSDET_GetSectorInfo()

返回数据结构列表

AEESMSMsg

说明：

此结构将作为 NMASK_TAPI_SMS_TEXT 或 NMASK_TAPI_SMS_TS 通知中 EVT_NOTIFY 事件部分的 dwParam 参数提供给应用程序。 dwParam 属于 AEENotify 类型。 成员 pData 包含实际消息， 将它传递到 ITAPI_ExtractSMSText() 可提取格式化文本。

定义：

无

成员：

无

备注：

无

另请参阅：

AEENotify

返回数据结构列表

AEESMSTextMsg

说明：

此结构将作为 NMASK_TAPI_SMS_TEXT 通知中 EVT_NOTIFY 事件部分的 dwParam 参数提供给应用程序。 dwParam 属于 AEENotify 类型。 成员 pData 包含实际消息， 将它传递到 ITAPI_ExtractSMSText() 可提取格式化文本。

定义：

typedef struct
{
uint16 nChars;
char szText[1];
} AEESMSTextMsg;

成员：

nChars | 字符数。
szText[1] | 文本大小

备注：

无

另请参阅：

ITAPI_ExtractSMSText()

返回数据结构列表

AEESoundAPath

说明：

AEESoundAPath 用于指示 ISound 接口能否在通话时无线传输音调。

定义：

typedef enum
{
AEE_SOUND_APATH_LOCAL,
AEE_SOUND_APATH_TX,
AEE_SOUND_APATH_BOTH,
AEE_SOUND_APATH_MUTE,
AEE_SOUND_APATH_LAST
} AEESoundAPath;

成员：

AEE_SOUND_APATH_LOCAL | 本地音频的 DTMF。
AEE_SOUND_APATH_TX | 传输 DTMF。
AEE_SOUND_APATH_BOTH | 本地传输和发出 DTMF。
AEE_SOUND_APATH_MUTE | 静音 DTMF。
AEE_SOUND_APATH_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundCmd

说明：

AEESoundCmd 用于指定 ISound 向应用程序发送事件和数据所使用的回调类型。

定义：

typedef enum {AEE_SOUND_STATUS_CB, AEE_SOUND_VOLUME_CB} AEESoundCmd;

成员：

AEE_SOUND_STATUS_CB | ISound 状态回调。
AEE_SOUND_VOLUME_CB | 获取音量回调。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundCmdData

说明：

AEESoundCmdData 用于指定通过回调发送给应用程序的数据。

定义：

typedef union
{
uint16 wVolume;
uint16 wPlayIndex;
} AEESoundCmdData;

成员：

wVolume | 通过音量回调发送的音量。
wPlayIndex | 当前要播放的音调。 通过 PlayToneList 状态回调发送。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundDevice

说明：

AEESoundDevice 用于指定 ISound 接口选择和使用的设备。

定义：

typedef enum
{
AEE_SOUND_DEVICE_UNKNOWN,
AEE_SOUND_DEVICE_HANDSET,
AEE_SOUND_DEVICE_HFK,
AEE_SOUND_DEVICE_HEADSET,
AEE_SOUND_DEVICE_AHFK,
AEE_SOUND_DEVICE_SDAC,
AEE_SOUND_DEVICE_TTY_HFK,
AEE_SOUND_DEVICE_TTY_HEADSET,
AEE_SOUND_DEVICE_CURRENT,
AEE_SOUND_DEVICE_LAST
} AEESoundDevice;

成员：

AEE_SOUND_DEVICE_UNKNOWN | 未知设备。
AEE_SOUND_DEVICE_HANDSET | 手持设备。
AEE_SOUND_DEVICE_HFK | 免提工具 (HFK)。
AEE_SOUND_DEVICE_HEADSET | 耳机。
AEE_SOUND_DEVICE_AHFK | 模拟 HFK。
AEE_SOUND_DEVICE_SDAC | 立体声 DAC。
AEE_SOUND_DEVICE_TTY_HFK | TTY HFK。
AEE_SOUND_DEVICE_TTY_HEADSET | TTY 耳机。
AEE_SOUND_DEVICE_CURRENT | 当前已选择的设备。
AEE_SOUND_DEVICE_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundInfo

说明：

AEESoundInfo 用于指定 ISound 在其全部操作中使用的 ISound 属性。

定义：

typedef structure
{
AEESoundDevice eDevice;
AEESoundMethod eMethod;
AEESoundAPath eAPath;
AEESoundMuteCtl eEarMuteCtl;
AEESoundMuteCtl eMicMuteCtl;
} AEESoundInfo;

成员：

eDevice | 使用的设备。
eMethod | 使用的方法。
eAPath | 无线音频路径。
eEarMuteCtl | 听筒静音控制。
eMicMuteCtl | 话筒静音控制。

备注：

无

另请参阅：

AEESoundDevice

AEESoundMethod

AEESoundAPath

AEESoundMuteCtl

返回数据结构列表

AEESoundMethod

说明：

AEESoundMethod 用于指定 ISound 接口使用的方法。

定义：

typedef enum
{
AEE_SOUND_METHOD_UNKNOWN,
AEE_SOUND_METHOD_VOICE,
AEE_SOUND_METHOD_BEEP,
AEE_SOUND_METHOD_MESSAGE,
AEE_SOUND_METHOD_RING,
AEE_SOUND_METHOD_CLICK,
AEE_SOUND_METHOD_MIDI,
AEE_SOUND_METHOD_AUX,
AEE_SOUND_METHOD_LAST
} AEESoundMethod;

成员：

AEE_SOUND_METHOD_UNKNOWN | 未知方法。
AEE_SOUND_METHOD_VOICE | 使用设备的语音发生器。
AEE_SOUND_METHOD_BEEP | 使用设备的按键音发生器。
AEE_SOUND_METHOD_MESSAGE | 使用路径振铃器或语音发生器。
AEE_SOUND_METHOD_RING | 使用设备的铃声发生器。
AEE_SOUND_METHOD_CLICK | 使用设备的滴答声发生器。
AEE_SOUND_METHOD_MIDI | 使用设备的 Midi 发生器。
AEE_SOUND_METHOD_AUX | 如果可用，使用设备的辅助发生器。
AEE_SOUND_METHOD_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundMuteCtl

说明：

AEESoundMuteCtl 用于控制听筒和话筒静音。

定义：

typedef enum
{
AEE_SOUND_MUTECTL_UNMUTED,
AEE_SOUND_MUTECTL_MUTED,
AEE_SOUND_MUTECTL_LAST
} AEESoundMuteCtl;

成员：

AEE_SOUND_MUTECTL_UNMUTED | 音频路径未静音。
AEE_SOUND_MUTECTL_MUTED | 音频路径静音。
AEE_SOUND_MUTECTL_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerAudioSpec

说明：

AEESoundPlayerAudioSpec 用于指示音频的规范说明。 与 AEESOUNDPLAYER_AUDIO_SPEC 播放回调共同使用。

定义：

typedef union
{
AEESoundPlayerFile fType;
AEESoundPlayerMIDISpec MIDISpec;
AEESoundPlayerMP3Spec MP3Spec;
} AEESoundPlayerAudioSpec;

成员：

fType | 音频文件类型。
MIDISpec | MIDI 规范说明（如果文件类型为 MIDI）。
MP3Spec | MP3 规范说明（如果文件类型为 MP3）。

备注：

无

另请参阅：

AEESoundPlayerFile

AEESoundPlayerMIDISpec

AEESoundPlayerMP3Spec

返回数据结构列表

AEESoundPlayerCmd

说明：

AEESoundPlayerCmd 用于指定 ISoundPlayer 向应用程序发送事件和数据所使用的回调类型。

定义：

typedef enum
{
AEE_SOUNDPLAYER_STATUS_CB,
AEE_SOUNDPLAYER_PLAY_CB,
AEE_SOUNDPLAYER_TIME_CB,
AEE_SOUNDPLAYER_SOUND_CB,
AEE_SOUNDPLAYER_VOLUME_CB
} AEESoundPlayerCmd;

成员：

AEE_SOUNDPLAYER_STATUS_CB | SoundPlayer 状态回调。
AEE_SOUNDPLAYER_PLAY_CB | 播放回调。
AEE_SOUNDPLAYER_TIME_CB | 获取时间回调。
AEE_SOUNDPLAYER_SOUND_CB | 声音回调。
AEE_SOUNDPLAYER_VOLUME_CB | 获取音量回调。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerCmdData

说明：

AEESoundPlayerCmdData 用于指定通过回调发送给应用程序的数据。

定义：

typedef union
{
uint32 dwElapsedTime;
uint32 dwTotalTime;
uint32 dwTempo;
uint32 dwTune;
uint32 dwPan;
uint16 wVolume;
AEESoundPlayerAudioSpec spSpec;
} AEESoundPlayerCmdData;

成员：

dwElapsedTime | 通过“暂停”、“恢复”、“倒回”和“快进”等播放回调发送的使用时间。
dwTotalTime | 通过获取时间回调发送的总时间。
dwTempo | 通过 SetTempo 播放回调发送的速度系数。
dwTune | 通过 SetTune 播放回调发送的音质系数。
dwPan | 未使用。
wVolume | 指示设备/方法对的音量。 其范围从 0（零）至 AEE_MAX_VOLUME。
spSpec | 通过“播放”播放回调发送的音频规范说明。

备注：

无

另请参阅：

AEESoundPlayerAudioSpec

返回数据结构列表

AEESoundPlayerFile

说明：

AEESoundPlayerFile 用于指示正在播放的文件类型。

定义：

typedef enum
{
AEE_SOUNDPLAYER_FILE_UNKNOWN,
AEE_SOUNDPLAYER_FILE_MIDI,
AEE_SOUNDPLAYER_FILE_MP3,
AEE_SOUNDPLAYER_FILE_LAST
} AEESoundPlayerFile;

成员：

AEE_SOUNDPLAYER_FILE_UNKNOWN | 无效类型。
AEE_SOUNDPLAYER_FILE_MIDI | MIDI。
AEE_SOUNDPLAYER_FILE_MP3 | MP3。
AEE_SOUNDPLAYER_FILE_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerInfo

说明：

AEESoundPlayerInfo 用于指定音频源。 它可以通过 ISOUNDPLAYER_SetInfo() 设置 ISoundPlayer 音频源。

定义：

typedef structure
{
AEESoundPlayerInput eInput;
void * pData;
uint32 dwSize;
} AEESoundPlayerInfo;

成员：

eInput | 音频源（输入）类型。 可以是文件或缓冲区。
pData | 根据输入类型指向文件名或缓冲区的指针。
dwSize | 缓冲区中的数据大小。 仅对缓冲区输入类型有效。

备注：

pData 参数归应用程序所有， ISoundPlayer 不分配或取消分配 pData。

另请参阅：

AEESoundPlayerInput

返回数据结构列表

AEESoundPlayerInput

说明：

AEESoundPlayerInput 用于指示 ISoundPlayer 查找要播放的数据或文件的源。

定义：

typedef enum
{
SDT_NONE,
SDT_FILE,
SDT_BUFFER,
SDT_VOICEPROMPT
} AEESoundPlayerInput;

成员：

SDT_NONE | 未知源（保留）。
SDT_FILE | 指定数据为文件名。
SDT_BUFFER | 指定数据为原始缓冲区（保留）。
SDT_VOICEPROMPT | 未使用。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMIDISpec

说明：

AEESoundPlayerMIDISpec 用于指示 MIDI 文件类型的音频规范说明。 与 AEESoundPlayerAudioSpec 播放回调共同使用。

定义：

typedef structure {AEESoundPlayerFile fType;} AEESoundPlayerMIDISpec;

成员：

fType
音频文件格式。

备注：

无

另请参阅：

AEESoundPlayerFile

返回数据结构列表

AEESoundPlayerMP3BitRate

说明：

AEESoundPlayerMP3BitRate 用于指定 MP3 比特率。

定义：

typedef enum
{
AEE_SOUNDPLAYER_MP3_BITRATE_FREE = 0,
AEE_SOUNDPLAYER_MP3_BITRATE_8K = 8,
AEE_SOUNDPLAYER_MP3_BITRATE_16K = 16,
AEE_SOUNDPLAYER_MP3_BITRATE_24K = 24,
AEE_SOUNDPLAYER_MP3_BITRATE_32K = 32,
AEE_SOUNDPLAYER_MP3_BITRATE_40K = 40,
AEE_SOUNDPLAYER_MP3_BITRATE_48K = 48,
AEE_SOUNDPLAYER_MP3_BITRATE_56K = 56,
AEE_SOUNDPLAYER_MP3_BITRATE_64K = 64,
AEE_SOUNDPLAYER_MP3_BITRATE_80K = 80,
AEE_SOUNDPLAYER_MP3_BITRATE_96K = 96,
AEE_SOUNDPLAYER_MP3_BITRATE_112K = 112,
AEE_SOUNDPLAYER_MP3_BITRATE_128K = 128,
AEE_SOUNDPLAYER_MP3_BITRATE_144K = 144,
AEE_SOUNDPLAYER_MP3_BITRATE_160K = 160,
AEE_SOUNDPLAYER_MP3_BITRATE_176K = 176,
AEE_SOUNDPLAYER_MP3_BITRATE_192K = 192,
AEE_SOUNDPLAYER_MP3_BITRATE_224K = 224,
AEE_SOUNDPLAYER_MP3_BITRATE_256K = 256,
AEE_SOUNDPLAYER_MP3_BITRATE_288K = 288,
AEE_SOUNDPLAYER_MP3_BITRATE_320K = 320,
AEE_SOUNDPLAYER_MP3_BITRATE_352K = 352,
AEE_SOUNDPLAYER_MP3_BITRATE_384K = 384,
AEE_SOUNDPLAYER_MP3_BITRATE_416K = 416,
AEE_SOUNDPLAYER_MP3_BITRATE_448K = 448,
AEE_SOUNDPLAYER_MP3_BITRATE_VAR = 500,
AEE_SOUNDPLAYER_MP3_BITRATE_UNK = 501
} AEESoundPlayerMP3BitRate;

成员：

下面是“自由”比特率（由软件确定）

AEE_SOUNDPLAYER_MP3_BITRATE_FREE

以下为“固定”比特率

AEE_SOUNDPLAYER_MP3_BITRATE_8K

AEE_SOUNDPLAYER_MP3_BITRATE_16K

AEE_SOUNDPLAYER_MP3_BITRATE_24K

AEE_SOUNDPLAYER_MP3_BITRATE_32K

AEE_SOUNDPLAYER_MP3_BITRATE_40K

AEE_SOUNDPLAYER_MP3_BITRATE_48K

AEE_SOUNDPLAYER_MP3_BITRATE_56K

AEE_SOUNDPLAYER_MP3_BITRATE_64K

AEE_SOUNDPLAYER_MP3_BITRATE_80K

AEE_SOUNDPLAYER_MP3_BITRATE_96K

AEE_SOUNDPLAYER_MP3_BITRATE_112K

AEE_SOUNDPLAYER_MP3_BITRATE_128K

AEE_SOUNDPLAYER_MP3_BITRATE_144K

AEE_SOUNDPLAYER_MP3_BITRATE_160K

AEE_SOUNDPLAYER_MP3_BITRATE_176K

AEE_SOUNDPLAYER_MP3_BITRATE_192K

AEE_SOUNDPLAYER_MP3_BITRATE_224K

AEE_SOUNDPLAYER_MP3_BITRATE_256K

AEE_SOUNDPLAYER_MP3_BITRATE_288K

AEE_SOUNDPLAYER_MP3_BITRATE_320K

AEE_SOUNDPLAYER_MP3_BITRATE_352K

AEE_SOUNDPLAYER_MP3_BITRATE_384K

AEE_SOUNDPLAYER_MP3_BITRATE_416K

AEE_SOUNDPLAYER_MP3_BITRATE_448K

下面是“可变”波特率（每帧都变化）

AEE_SOUNDPLAYER_MP3_BITRATE_VAR

无法确定比特率信息

AEE_SOUNDPLAYER_MP3_BITRATE_UNK

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3Channel

说明：

AEESoundPlayerMP3Channel 用于指定 MP3 声道。

定义:

typedef enum
{
AEE_SOUNDPLAYER_MP3_CHANNEL_STEREO,
AEE_SOUNDPLAYER_MP3_CHANNEL_JOINT_STEREO,
AEE_SOUNDPLAYER_MP3_CHANNEL_DUAL,
AEE_SOUNDPLAYER_MP3_CHANNEL_SINGLE
} AEESoundPlayerMP3Channel;

成员：

AEE_SOUNDPLAYER_MP3_CHANNEL_STEREO | 立体声数据。
AEE_SOUNDPLAYER_MP3_CHANNEL_JOINT_STEREO | 混合立体声数据。
AEE_SOUNDPLAYER_MP3_CHANNEL_DUAL | 双声道（立体声）数据。
AEE_SOUNDPLAYER_MP3_CHANNEL_SINGLE | 单声道数据。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3Emphasis

说明：

AEESoundPlayerMP3Emphasis 用于指定 MP3 加强标记。

定义：

typedef enum
{
AEE_SOUNDPLAYER_MP3_EMPHASIS_NONE,
AEE_SOUNDPLAYER_MP3_EMPHASIS_50_15_MS,
AEE_SOUNDPLAYER_MP3_EMPHASIS_RESERVED,
AEE_SOUNDPLAYER_MP3_EMPHASIS_CCITT_J17
} AEESoundPlayerMP3Emphasis;

成员：

AEE_SOUNDPLAYER_MP3_EMPHASIS_NONE | 无效标记。
AEE_SOUNDPLAYER_MP3_EMPHASIS_50_15_MS | 50_15_MS。
AEE_SOUNDPLAYER_MP3_EMPHASIS_RESERVED | 保留。
AEE_SOUNDPLAYER_MP3_EMPHASIS_CCITT_J17 | CCITT J17。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3Extension

说明：

AEESoundPlayerMP3Extension 用于指定 1-3 层 MP3 扩展。

定义：

typedef enum
{
AEE_SOUNDPLAYER_MP3_EXT_BAND_4_31 = 0,
AEE_SOUNDPLAYER_MP3_EXT_BAND_8_31 = 1,
AEE_SOUNDPLAYER_MP3_EXT_BAND_12_31 = 2,
AEE_SOUNDPLAYER_MP3_EXT_BAND_16_31 = 3,
AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_OFF_MS_OFF = 0,
AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_ON_MS_OFF = 1,
AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_OFF_MS_ON = 2,
AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_ON_MS_ON = 3
} AEESoundPlayerMP3Extension;

成员：

对于 1 层和 2 层文件 |  |
 | AEE_SOUNDPLAYER_MP3_EXT_BAND_4_31 | 声道扩展信息，4-31。
 | AEE_SOUNDPLAYER_MP3_EXT_BAND_8_31 | 声道扩展信息，8-31。
 | AEE_SOUNDPLAYER_MP3_EXT_BAND_12_31 | 声道扩展信息，12-31。
 | AEE_SOUNDPLAYER_MP3_EXT_BAND_16_31 | 声道扩展信息，16-31。

对于第 3 层文件 |  |
 | AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_OFF_MS_OFF | 关闭强立体声和 MS。
 | AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_ON_MS_OFF | 打开强立体声，关闭 MS。
 | AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_OFF_MS_ON | 关闭强立体声，打开 MS。
 | AEE_SOUNDPLAYER_MP3_EXT_INTENSITY_ON_MS_ON | 打开强立体声和 MS。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3Layer

说明：

AEESoundPlayerMP3Layer 用于指定 MPEG 层信息。

定义：

typedef enum
{
AEE_SOUNDPLAYER_LAYER_RESERVED,
AEE_SOUNDPLAYER_LAYER_3,
AEE_SOUNDPLAYER_LAYER_2,
AEE_SOUNDPLAYER_LAYER_1,
AEE_SOUNDPLAYER_LAYER_UNKNOWN
} AEESoundPlayerMP3Layer;

成员：

AEE_SOUNDPLAYER_LAYER_RESERVED | 保留。
AEE_SOUNDPLAYER_LAYER_3 | MPEG 3 层压缩。
AEE_SOUNDPLAYER_LAYER_2 | MPEG 2 层压缩。
AEE_SOUNDPLAYER_LAYER_1 | MPEG 1 层压缩。
AEE_SOUNDPLAYER_LAYER_UNKNOWN | 无法确定层信息。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3SampleRate

说明：

AEESoundPlayerMP3SampleRate 用于指定 MP3 的采样率。

定义：

typedef enum
{
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_UNKNOWN,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_8000 = 1,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_11025,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_12000,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_16000,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_22050,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_24000,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_32000,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_44100,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_48000,
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_LAST
} AEESoundPlayerMP3SampleRate;

成员：

AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_UNKNOWN | 未知采样率。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_8000 | 8k
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_11025 | 11.025k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_12000 | 12k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_16000 | 16k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_22050 | 22.050k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_24000 | 24k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_32000 | 32k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_44100 | 44.1k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_48000 | 48k。
AEE_SOUNDPLAYER_MP3_SAMPLE_RATE_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerMP3Spec

说明：

AEESoundPlayerMP3Spec 用于指示 MP3 文件类型的音频规范说明。 与 AEESOUNDPLAYER_AUDIO_SPEC 播放回调共同使用。

定义：

typedef structure
{
AEESoundPlayerFile fType;
AEESoundPlayerMP3Version version;
AEESoundPlayerMP3Layer layer;
boolean crcFlag;
AEESoundPlayerMP3BitRate bitrate;
AEESoundPlayerMP3SampleRate sampleRate;
AEESoundPlayerMP3Channel channel;
AEESoundPlayerMP3Extension extension;
boolean copyrightFlag;
boolean originalFlag;
AEESoundPlayerMP3Emphasis emphasis;
char title[AEE_ID3_TAG_LENGTH];
char artist[AEE_ID3_TAG_LENGTH];
char album[AEE_ID3_TAG_LENGTH];
char year[4];
char comment[AEE_ID3_TAG_LENGTH];
uint8 genre;
} AEESoundPlayerMP3Spec;

成员：

fType | 音频文件格式。
version | MPEG 版本。
layer | MPEG 层说明。
crcFlag | TRUE（如果使用 CRC 保护）
bitrate | 比特率。
sampleRate | 采样率。
channel | 声道模式。
extension | 仅在声道为 AEE_SOUNDPLAYER_MP3_ CHANNEL_JOINT_STEREO 时使用。
copyrightFlag | TRUE（如果拥有版权）。
originalFlag | TRUE（如果为原版）
emphasis | 音频加强。
title | 歌曲标题。
artist | 歌曲演绎者。
album | 歌曲专辑。
year | 发行专辑的年份。
comment | 文本注释。
genre | ID3 类型标签。

备注：

无

另请参阅：

AEESoundPlayerFile

AEESoundPlayerMP3Version

AEESoundPlayerMP3Layer

AEESoundPlayerMP3BitRate

AEESoundPlayerMP3SampleRate

AEESoundPlayerMP3Channel

AEESoundPlayerMP3Extension

AEESoundPlayerMP3Emphasis

返回数据结构列表

AEESoundPlayerMP3Version

说明：

AEESoundPlayerMP3Version 用于指定 MPEG 版本类型。

定义：

typedef enum
{
AEE_SOUNDPLAYER_MP3_VERSION_25,
AEE_SOUNDPLAYER_MP3_VERSION_RESERVED,
AEE_SOUNDPLAYER_MP3_VERSION_2,
AEE_SOUNDPLAYER_MP3_VERSION_1,
AEE_SOUNDPLAYER_MP3_VERSION_UNKNOWN
} AEESoundPlayerMP3Version;

成员：

AEE_SOUNDPLAYER_MP3_VERSION_25 | MPEG 2.5 版。
AEE_SOUNDPLAYER_MP3_VERSION_RESERVED | 保留。
AEE_SOUNDPLAYER_MP3_VERSION_2 | MPEG 2.0 版。
AEE_SOUNDPLAYER_MP3_VERSION_1 | MPEG 1.0 版。
AEE_SOUNDPLAYER_MP3_VERSION_UNKNOWN | 无法确定版本。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerSource

说明：

AEESoundPlayerSource 由 ISoundPlayer 接口内部使用。

定义：

typedef enum
{
AEE_SOUNDPLAYER_SOURCE_UNKNOWN,
AEE_SOUNDPLAYER_SOURCE_MEM,
AEE_SOUNDPLAYER_SOURCE_FILE,
AEE_SOUNDPLAYER_SOURCE_LAST
} AEESoundPlayerSource;

成员：

AEE_SOUNDPLAYER_SOURCE_UNKNOWN | 无效类型。
AEE_SOUNDPLAYER_SOURCE_MEM | 在内存中找到数据。
AEE_SOUNDPLAYER_SOURCE_FILE | 在嵌入式文件系统 (EFS) 中找到数据。
AEE_SOUNDPLAYER_SOURCE_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundPlayerStatus

说明：

回调函数返回 AEESoundPlayerStatus 以指示 ISoundPlayer 事件并将数据返回给应用程序。

定义：

typedef enum
{
AEE_SOUNDPLAYER_UNKNOWN,
AEE_SOUNDPLAYER_SUCCESS,
AEE_SOUNDPLAYER_REWIND,
AEE_SOUNDPLAYER_FFORWARD,
AEE_SOUNDPLAYER_PAUSE,
AEE_SOUNDPLAYER_RESUME,
AEE_SOUNDPLAYER_TEMPO,
AEE_SOUNDPLAYER_TUNE,
AEE_SOUNDPLAYER_PAN,
AEE_SOUNDPLAYER_AUDIO_SPEC,
AEE_SOUNDPLAYER_TICK_UPDATE,
AEE_SOUNDPLAYER_DATA_ACCESS_DELAY,
AEE_SOUNDPLAYER_ABORTED,
AEE_SOUNDPLAYER_REPEAT,
AEE_SOUNDPLAYER_DONE,
AEE_SOUNDPLAYER_FAILURE,
AEE_SOUNDPLAYER_LAST
} AEESoundPlayerStatus;

成员：

AEE_SOUNDPLAYER_UNKNOWN | 未知状态。
AEE_SOUNDPLAYER_SUCCESS | 已接受请求。
AEE_SOUNDPLAYER_REWIND | 播放当前正在倒回。
AEE_SOUNDPLAYER_FFORWARD | 播放当前正在快进。
AEE_SOUNDPLAYER_PAUSE | 当前播放已暂停。
AEE_SOUNDPLAYER_RESUME | 播放已恢复。
AEE_SOUNDPLAYER_TEMPO | 播放速度已更改。
AEE_SOUNDPLAYER_TUNE | 播放音质已更改。
AEE_SOUNDPLAYER_PAN | 播放立体声定位已更改。
AEE_SOUNDPLAYER_AUDIO_SPEC | 音频规范说明信息。
AEE_SOUNDPLAYER_TICK_UPDATE | 播放时一秒更新。
AEE_SOUNDPLAYER_DATA_ACCESS_DELAY | 播放因数据访问而延迟。
AEE_SOUNDPLAYER_ABORTED | 命令已中止。
AEE_SOUNDPLAYER_REPEAT | 声音重复。
AEE_SOUNDPLAYER_DONE | 命令已执行。
AEE_SOUNDPLAYER_FAILURE | 请求出错。
AEE_SOUNDPLAYER_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundStatus

说明：

回调函数返回 AEESoundStatus 以指示 ISound 事件并将数据返回给应用程序。

定义：

typedef enum
{
AEE_SOUND_UNKNOWN,
AEE_SOUND_SUCCESS,
AEE_SOUND_PLAY_DONE,
AEE_SOUND_FAILURE,
AEE_SOUND_LAST
} AEESoundStatus;

成员：

AEE_SOUND_UNKNOWN | 未知状态。
AEE_SOUND_SUCCESS | 已接受请求。
AEE_SOUND_PLAY_DONE | 音调已完成播放或被其它音调覆盖。
AEE_SOUND_FAILURE | 请求出错。
AEE_SOUND_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundTone

说明：

AEESoundTone 用于指定 ISound 播放音调所使用的音调标识符。

定义：

typedef enum
{
AEE_TONE_FIRST,
AEE_TONE_0,
AEE_TONE_1,
AEE_TONE_2,
AEE_TONE_3,
AEE_TONE_4,
AEE_TONE_5,
AEE_TONE_6,
AEE_TONE_7,
AEE_TONE_8,
AEE_TONE_9,
AEE_TONE_A,
AEE_TONE_B,
AEE_TONE_C,
AEE_TONE_D,
AEE_TONE_POUND,
AEE_TONE_STAR,
AEE_TONE_CTRL,
AEE_TONE_2ND,
AEE_TONE_WARN,
AEE_TONE_ERR,
AEE_TONE_TIME,
AEE_TONE_RING_A,
AEE_TONE_RING_B,
AEE_TONE_RING_C,
AEE_TONE_RING_D,
AEE_TONE_RING_A4,
AEE_TONE_RING_AS4,
AEE_TONE_RING_B4,
AEE_TONE_RING_C4,
AEE_TONE_RING_CS4,
AEE_TONE_RING_D4,
AEE_TONE_RING_DS4,
AEE_TONE_RING_E4,
AEE_TONE_RING_F4,
AEE_TONE_RING_FS4,
AEE_TONE_RING_G4,
AEE_TONE_RING_GS4,
AEE_TONE_RING_A5,
AEE_TONE_RING_AS5,
AEE_TONE_RING_B5,
AEE_TONE_RING_C5,
AEE_TONE_RING_CS5,
AEE_TONE_RING_D5,
AEE_TONE_RING_DS5,
AEE_TONE_RING_E5,
AEE_TONE_RING_F5,
AEE_TONE_RING_FS5,
AEE_TONE_RING_G5,
AEE_TONE_RING_GS5,
AEE_TONE_RING_A6,
AEE_TONE_RING_AS6,
AEE_TONE_RING_B6,
AEE_TONE_RING_C6,
AEE_TONE_RING_CS6,
AEE_TONE_RING_D6,
AEE_TONE_RING_DS6,
AEE_TONE_RING_E6,
AEE_TONE_RING_F6,
AEE_TONE_RING_FS6,
AEE_TONE_RING_G6,
AEE_TONE_RING_GS6,
AEE_TONE_RING_A7,
AEE_TONE_RBACK,
AEE_TONE_BUSY,
AEE_TONE_INTERCEPT_A,
AEE_TONE_INTERCEPT_B,
AEE_TONE_REORDER_TONE,
AEE_TONE_PWRUP,
AEE_TONE_OFF_HOOK_TONE,
AEE_TONE_CALL_WT_TONE,
AEE_TONE_DIAL_TONE_TONE,
AEE_TONE_ANSWER_TONE,
AEE_TONE_HIGH_PITCH_A,
AEE_TONE_HIGH_PITCH_B,
AEE_TONE_MED_PITCH_A,
AEE_TONE_MED_PITCH_B,
AEE_TONE_LOW_PITCH_A,
AEE_TONE_LOW_PITCH_B,
AEE_TONE_TEST_ON,
AEE_TONE_MSG_WAITING,
AEE_TONE_PIP_TONE_TONE,
AEE_TONE_SPC_DT_INDIA,
AEE_TONE_SIGNAL_INDIA,
AEE_TONE_DT_TONE_INDIA,
AEE_TONE_DT_TONE_BRAZIL,
AEE_TONE_DT_DTACO_TONE,
AEE_TONE_HFK_TONE1,
AEE_TONE_HFK_TONE2,
AEE_TONE_SILENCE
AEE_TONE_LAST
} AEESoundTone;

成员：

AEE_TONE_FIRST | 保留。
AEE_TONE_0 | 按键 0 的 DTMF。
AEE_TONE_1 | 按键 1 的 DTMF。
AEE_TONE_2 | 按键 2 的 DTMF。
AEE_TONE_3 | 按键 3 的 DTMF。
AEE_TONE_4 | 按键 4 的 DTMF。
AEE_TONE_5 | 按键 5 的 DTMF。
AEE_TONE_6 | 按键 6 的 DTMF。
AEE_TONE_7 | 按键 7 的 DTMF。
AEE_TONE_8 | 按键 8 的 DTMF。
AEE_TONE_9 | 按键 9 的 DTMF。
AEE_TONE_A | 按键 A 的 DTMF。
AEE_TONE_B | 按键 B 的 DTMF。
AEE_TONE_C | 按键 C 的 DTMF。
AEE_TONE_D | 按键 D 的 DTMF。
AEE_TONE_POUND | 按键 # 的 DTMF。
AEE_TONE_STAR | 按键 * 的 DTMF。
AEE_TONE_CTRL | 控制键音调。
AEE_TONE_2ND | 按键辅助功能的音调。
AEE_TONE_WARN | 警告音调（例如，改写设备用户电话号码位置）。
AEE_TONE_ERR | 指示错误的音调。
AEE_TONE_TIME | 时间标记音调。
AEE_TONE_RING_A | 第一种振铃器音调。
AEE_TONE_RING_B | 第二种振铃器音调。
AEE_TONE_RING_C | 第三种振铃器音调。
AEE_TONE_RING_D | 第四种振铃器音调。
AEE_TONE_RING_A4 | 440.0 赫兹 钢琴音符。
AEE_TONE_RING_AS4 | 466.1 赫兹。
AEE_TONE_RING_B4 | 493.8 赫兹。
AEE_TONE_RING_C4 | 523.2 赫兹。
AEE_TONE_RING_CS4 | 554.3 赫兹。
AEE_TONE_RING_D4 | 587.3 赫兹。
AEE_TONE_RING_DS4 | 622.2 赫兹。
AEE_TONE_RING_E4 | 659.2 赫兹。
AEE_TONE_RING_F4 | 698.5 赫兹。
AEE_TONE_RING_FS4 | 739.9 赫兹。
AEE_TONE_RING_G4 | 784.0 赫兹。
AEE_TONE_RING_GS4 | 830.6 赫兹。
AEE_TONE_RING_A5 | 880.0 赫兹。
AEE_TONE_RING_AS5 | 932.2 赫兹。
AEE_TONE_RING_B5 | 987.7 赫兹。
AEE_TONE_RING_C5 | 1046.5 赫兹。
AEE_TONE_RING_CS5 | 1108.7 赫兹。
AEE_TONE_RING_D5 | 1174.6 赫兹。
AEE_TONE_RING_DS5 | 1244.3 赫兹。
AEE_TONE_RING_E5 | 1318.5 赫兹。
AEE_TONE_RING_F5 | 1397.0 赫兹。
AEE_TONE_RING_FS5 | 1479.9 赫兹。
AEE_TONE_RING_G5 | 1568.0 赫兹。
AEE_TONE_RING_GS5 | 1661.2 赫兹。
AEE_TONE_RING_A6 | 1760.0 赫兹。
AEE_TONE_RING_AS6 | 1864.7 赫兹。
AEE_TONE_RING_B6 | 1975.5 赫兹。
AEE_TONE_RING_C6 | 2093.1 赫兹。
AEE_TONE_RING_CS6 | 2217.4 赫兹。
AEE_TONE_RING_D6 | 2349.3 赫兹。
AEE_TONE_RING_DS6 | 2489.1 赫兹。
AEE_TONE_RING_E6 | 2637.0 赫兹。
AEE_TONE_RING_F6 | 2793.7 赫兹。
AEE_TONE_RING_FS6 | 2959.9 赫兹。
AEE_TONE_RING_G6 | 3135.9 赫兹。
AEE_TONE_RING_GS6 | 3322.4 赫兹。
AEE_TONE_RING_A7 | 3520.0 赫兹。
AEE_TONE_RBACK | 回铃（可听振铃音）。
AEE_TONE_BUSY | 忙音。
AEE_TONE_INTERCEPT_A | 第一个中止音。
AEE_TONE_INTERCEPT_B | 第二个中止音。
AEE_TONE_REORDER_TONE | 录音器。
AEE_TONE_PWRUP | 开机音。
AEE_TONE_OFF_HOOK_TONE | 摘机音，IS-95 (CAI 7.7.5.5)。
AEE_TONE_CALL_WT_TONE | 通话等待音。
AEE_TONE_DIAL_TONE_TONE | 拨号音。
AEE_TONE_ANSWER_TONE | 应答音。
AEE_TONE_HIGH_PITCH_A | IS-54B 报警第一高音。
AEE_TONE_HIGH_PITCH_B | IS-54B 报警第二高音。
AEE_TONE_MED_PITCH_A | IS-54B 报警第一中音。
AEE_TONE_MED_PITCH_B | IS-54B 报警第二中音。
AEE_TONE_LOW_PITCH_A | IS-54B 报警第一低音。
AEE_TONE_LOW_PITCH_B | IS-54B 报警第二低音。
AEE_TONE_TEST_ON | 开启测试音。
AEE_TONE_MSG_WAITING | 消息等待音。
AEE_TONE_PIP_TONE_TONE | 用于 Pip-Pip-Pip-Pip（声码器）音调。
AEE_TONE_SPC_DT_INDIA | 用于印度特殊拨号音。
AEE_TONE_SIGNAL_INDIA | 用于不同的印度信号音。
AEE_TONE_DT_TONE_INDIA | 用于印度的普通拨号音（及其它）。
AEE_TONE_DT_TONE_BRAZIL | 用于巴西的拨号音。
AEE_TONE_DT_DTACO_TONE | 用于 DTACO 的单音调（350 赫兹、350 赫兹）。
AEE_TONE_HFK_TONE1 | 这两种音调用于“语音激活”。
AEE_TONE_HFK_TONE2 | 设备 VR-HFK 中的进入呼叫应答。
AEE_TONE_SILENCE | 控制音调 SND_SILENCE。
AEE_TONE_LAST | 保留。

备注：

无

另请参阅：

无

返回数据结构列表

AEESoundToneData

说明：

AEESoundToneData 用于指定音调 ID 和持续时间，以使用 ISOUND_PlayTone() 和 ISOUND_PlayToneList() 播放音调。

定义：

typedef structure
{
AEESoundTone eTone;
uint16 wDuration;
} AEESoundToneData ;

成员：

eTone | 音调 ID。
wDuration | 持续时间（毫秒）。

备注：

无

另请参阅：

AEESoundTone

返回数据结构列表

AEESpriteCmd

说明：

此结构用于说明 sprite。

定义

typedef struct {
int16 x;
int16 y;
uint16 unTransform;
uint8 unMatrixTransform;
uint8 unSpriteIndex;
uint8 unSpriteSize;
uint8 unComposite;
uint8 unLayer;
uint8 reserved[5];
} AEESpriteCmd;

成员：

x | 目标中的 x 坐标，在此将绘制未转换 sprite 的左上角。
y | 目标中的 y 坐标，在此将绘制未转换 sprite 的左上角。
unTransform | 包含 sprite 转换属性组合。
unMatrixTransform | 转换表中的转换索引。 只有在 unTransform 字段中置位 SPRITE_MATRIX_TRANSFORM 标记后才能应用矩阵转换。
unSpriteIndex | 要绘制的 sprite 图像索引。 源图像左上角坐标为 x = 0，y = unSpriteIndex * [sprite 高度]。
unSpriteSize | sprite 的大小。 有关有效值的信息，请参阅 SPRITE_SIZE_ 属性。
unComposite | 指定绘制 sprite 的方式为非透明还是透明。 请参阅组合属性。 (AEETransform.h)
unLayer | sprite 层。 先绘制低层。 请参阅 SPRITE_LAYER_ 属性。
reserved | 保留以备将来使用。 将它们设置为零“非常”重要。

备注：

无

另请参阅：

ISPRITE_DrawSprites()、

AEETransformMatrix (AEETransform.h)、

Sprite 属性

返回数据结构列表

AEESuspendReason

说明：

它将作为 wParam 随 EVT_APP_SUSPEND 事件一起发送。 该参数用于指定暂停应用程序的原因。

可能的取值如下：

AEE_SUSPEND_NORMAL： 因启动其它应用程序而被暂停

AEE_SUSPEND_EXTERNAL： 因外部事件而被暂停（例如进入呼叫）

定义：

typedef enum
{
AEE_SUSPEND_NORMAL, // 因启动其它应用程序而被暂停
AEE_SUSPEND_EXTERNAL // 因外部事件而被暂停
} AEESuspendReason;

成员：

AEE_SUSPEND_NORMAL: 因启动其它应用程序而被暂停

AEE_SUSPEND_EXTERNAL： 因外部事件而被暂停（例如进入呼叫）

备注：

无

另请参阅：

EVT_APP_SUSPEND

返回数据结构列表

AEESymbol

说明：

这是一个指定特殊符号的 uint16，所对应特殊字符的 AECHAR 值由 IDISPLAY_GetSymbol() 返回。 某些移动设备为这些符号定义了 AECHAR 值，并使用与符号对应的 AECHAR 字符串调用 IDISPLAY_DrawText()，在设备上绘制该符号。

定义：

#define AEESymbol uint16

预定义的符号如下：

AEE_SYM_ELLIPSES,
AEE_SYM_AM,
AEE_SYM_PM,
AEE_SYM_KEY_LEFT,
AEE_SYM_KEY_RIGHT,
AEE_SYM_KEY_CLR,
AEE_SYM_KEY_1,
AEE_SYM_KEY_2,
AEE_SYM_KEY_3,
AEE_SYM_KEY_4,
AEE_SYM_KEY_5,
AEE_SYM_KEY_6,
AEE_SYM_KEY_7,
AEE_SYM_KEY_8,
AEE_SYM_KEY_9,
AEE_SYM_KEY_0,
AEE_SYM_KEY_STAR,
AEE_SYM_KEY_POUND,
AEE_SYM_KEY_SEND,
AEE_SYM_KEY_END,
AEE_SYM_KEY_SELECT
AEE_SYM_USER

成员：

AEE_SYM_ELLIPSES | 椭圆符号。
AEE_SYM_AM | 指示 12 小时时间格式 AM 的符号。
AEE_SYM_PM | 指示 12 小时时间格式 PM 的符号。
AEE_SYM_KEY_LEFT | 左箭头键。
AEE_SYM_KEY_RIGHT | 右箭头键。
AEE_SYM_KEY_CLR | 清除键。
AEE_SYM_KEY_1 | 按键“1”。
AEE_SYM_KEY_2 | 按键“2”。
AEE_SYM_KEY_3 | 按键“3”。
AEE_SYM_KEY_4 | 按键“4”。
AEE_SYM_KEY_5 | 按键“5”。
AEE_SYM_KEY_6 | 按键“6”。
AEE_SYM_KEY_7 | 按键“7”。
AEE_SYM_KEY_8 | 按键“8”。
AEE_SYM_KEY_9 | 按键“9”。
AEE_SYM_KEY_0 | 按键“0”。
AEE_SYM_KEY_STAR | 按键“*”。
AEE_SYM_KEY_POUND | 按键“#”。
AEE_SYM_KEY_SEND | 按键“发送”或“呼叫”。
AEE_SYM_KEY_END | “结束”键。
AEE_SYM_KEY_SELECT | 选择键或“输入”键。
AEE_SYM_USER | 由 OEM 自定义的符号。

备注：

无

另请参阅：

无

返回数据结构列表

AEETextInputMode

说明：

该枚举类型用于指定文本输入模式，将文本输入到文本控件中。 函数 ITEXTCTL_SetInputMode() 选择用于特定文本控件实例的输入模式。

定义：

typedef enum
{
AEE_TM_NONE,
AEE_TM_CURRENT,
AEE_TM_SYMBOLS,
AEE_TM_LETTERS,
AEE_TM_RAPID,
AEE_TM_NUMBERS
} AEETextInputMode;

成员：

AEE_TM_NONE | 当前未指定输入模式。默认模式为 AEE_TM_LETTERS。
AEE_TM_CURRENT | 指定当前激活的输入模式。
AEE_TM_SYMBOLS | 按下按键将输入与该键相关联的特殊符号（如果有）。
AEE_TM_LETTERS | 按下按键将输入与该键相关联的字母（如果有）。
AEE_TM_RAPID | 使用快速 (T9) 模式。
AEE_TM_NUMBERS | 按下按键将输入与该键相关联的数字。
AEE_TM_MAX | AEE_TM_NUMBERS
AEE_TM_USER | AEE_TM_MAX +1
AEE_TM_FIRST_OEM | AEE_TM_USER，Oem 添加的模式从该值开始。
AEE_TM_RESERVED | 0x7000 及其上将保留 BREW 使用

备注：

每台 BREW 设备的可用文本输入模式可能有所不同。

另请参阅：

ITEXTCTL_SetInputMode()

返回数据结构列表

AEETextInputModeInfo

说明：

此结构包含一个 AEETextInputMode 和一个保存与该模式相关联字符串的缓冲区，
调用 ITEXTCTL_GetInputMode() 函数时将填入此字符串。

定义：

typedef structure _AEETextInputModeInfo
{
AEETextInputMode tmMode;
AECHAR modeString[MAX_TEXT_MODE_SIZE];
} AEETextInputModeInfo;

成员：

tmMode | 文本模式枚举条目。
modeString | 与模式相关联的字符串。

备注：

每台 BREW 设备的可用文本输入模式可能有所不同。

另请参阅：

ITEXTCTL_GetInputMode()

AEETextInputMode

返回数据结构列表

AEETileMap

说明：

此结构用于说明 tile 贴图。

定义

typedef struct {
uint16 *pMapArray;
uint32 unFlags;
uint32 reserved[4];
int32 x;
int32 y;
uint16 w;
uint16 h;
uint8 unTileSize;
uint8 reserved2[3];
} AEETileMap;

成员：

pMapArray | Tile 索引和属性数组。 它是二维贴图的一维表示。 展开贴图的各行即可构造此一维数组。 （第二行的第一个元素紧随第一个行的最后一个元素）。 每个元素的最后十位用作 tile 缓冲区内的索引。 （TILE_INDEX_MASK 屏蔽了这些位。） 特殊索引值 TILE_INDEX_NOTHING 表示“不要在此处绘制 tile”。 TILE_FLIP_、TILE_ROTATE_ 和 TILE_TRANSPARENT 标记均可应用于数组中的元素。 特殊值 pMapArray == NULL 表示它是传递到 ISPRITE_DrawTiles() 的数组中最后一个 AEETileMap 结构。 在这种情况下，AEETileMap 结构中的其它成员将被忽略。
unFlags | 应用于整个 tile 贴图的标记。 当前，只定义了 MAP_FLAG_WRAP。
reserved | 保留以备将来使用。 将它们设置为零“非常”重要。
x | 屏幕 x 坐标，在此将绘制背景左上角。
y | 屏幕 y 坐标，在此将绘制背景左上角。
w | Tile 贴图的宽度尺寸，按 tile 单位指定。 它们都不是直接尺寸， 而是在此使用 MAP_SIZE_ 值。
h | Tile 贴图的高度尺寸，按 tile 单位指定。 它们都不是直接尺寸， 而是在此使用 MAP_SIZE_ 值。
unTileSize | Tile 的大小。 它是 TILE_SIZE_ 值之一。
reserved2 | 保留以备将来使用。 将它们设置为零“非常”重要。

备注：

无

另请参阅：

ISPRITE_DrawTiles()、

Tile 属性

Tile 贴图属性

返回数据结构列表

AEETriangle

说明：

此结构用于定义三角形数据类型。

定义：

typedef structure _triangle
{
int16 x0, y0;
int16 x1, y1;
int16 x2, y2;
} AEETriangle;

成员：

x0 | 三角形第一个顶点的 X 坐标。
y0 | 第一个顶点的 Y 坐标。
x1 | 第二个顶点的 X 坐标。
y1 | 第二个顶点的 Y 坐标。
x2 | 第三个顶点的 X 坐标。
y2 | 第三个顶点的 Y 坐标。

备注：

无

另请参阅：

IGRAPHICS_DrawTriangle()

IGRAPHICS_Translate()

返回数据结构列表

AEEVoicePrompt

说明：

AEEVoicePrompt 未实现。

定义：

typedef structure
{
byte * pbData;
uint16 wNumFrames;
} AEEVoicePrompt;

成员：

pbData | 未实现。
wNumFrames | 未实现。

备注：

无

另请参阅：

无

返回数据结构列表

BeepType

说明：

该 ENUM 用于指定 ISHELL_Beep() 函数中的蜂鸣声类型。

定义：

typedef enum
{
BEEP_OFF,
BEEP_ALERT,
BEEP_REMINDER,
BEEP_MSG,
BEEP_ERROR,
BEEP_VIBRATE_ALERT,
BEEP_VIBRATE_REMIND
} BeepType;

成员：

BEEP_OFF | 关闭蜂鸣声。
BEEP_ALERT | 警告设备用户的蜂鸣声。
BEEP_REMINDER | 提醒信号蜂鸣声。
BEEP_MSG | 指示 SMS 消息到达的蜂鸣声。
BEEP_ERROR | 指示错误的蜂鸣声。
BEEP_VIBRATE_ALERT | 警告设备用户的无声模式振动。
BEEP_VIBRATE_REMIND | 提醒设备用户的无声模式振动。

备注：

目标设备上的 BeepType 取决于设备制造商。 设备制造商或应用程序开发者可在 BREW Emulator 中定义自己的 BeepType 音调。 例如，要创建 BEEP_ALERT 音调，需在 \Brew\bin\DataFiles 目录中将 .WAV 文件保存为 BEEP_ALERT.wav。 目前已为全部蜂鸣声类型提供示例音调，并在示例声音应用程序中说明它们的用法。

另请参阅：

无

返回数据结构列表

CtlAddItem

说明：

对添加到控件中的控件项目的封装。

定义：

typedef structure _CtlAddItem
{
const AECHAR * pText;
IImage * pImage;
const char * pszResImage;
const char * pszResText;
uint16 wText;
uint16 wFont;
uint16 wImage;
uint16 wItemID;
uint32 dwData;
} CtlAddItem;

成员：

pText | 项目中的文本。
pImage | 项目中的图像。
pszResImage | 资源文件名。
pszResText | 资源文件名。
wText | 文本字符串资源 ID。
wFont | 0（零）。 默认值。
wImage | 图像的资源 ID。
wItemID | 控件项 ID。
dwData | 与菜单项相关联的数据值。

备注：

默认使用 pText 和 pImage。 如果没有设置它们（即为 NULL），则通过 wText 和 wImage 使用 pszResImage 和 pszResText 分别加载文本或图像。

另请参阅：

无

返回数据结构列表

CtlValChange

说明：

此数据结构将作为 dwParam 随事件 EVT_CTL_CHANGING 一起传递。 该事件可在特定控件发生更改时发送到应用程序， 从而使得应用程序可以刷新屏幕的任何部分。

定义：

typedef struct _CtlValChange
{
IControl * pc;
uint32 dwParam;
boolean bValid;
} CtlValChange;

成员：

pc | 指向正在更改的控件的指针
dwParam | 控件特定的数据。 对于 ITimeCtl 接口，它指定了当前时间 （以毫秒为单位）
bValid | 可由应用程序在从事件返回时设置的参数。 如果应用程序将 bValid 设置为 FALSE，则控件不会根据新值进行刷新

备注：

此事件只能由特定控件发送。 例如 TimeCtl。 有关此事件的详细信息，请参阅特定控件

另请参阅：

无

返回数据结构列表

DialogInfo

说明：

该 ENUM 用于指定识别资源文件资源的资源类型。

定义：

typedef structure
{
DialogInfoHead h;
DialogItem controls[1];
} DialogInfo;

成员：

h | 对话框信息题头。
controls | 对话框项目数组。

备注：

无

另请参阅：

DialogItem

返回数据结构列表

DialogInfoHead

说明：

此结构用于指定对话框信息题头。

定义：

typedef structure
{
uint16 wID;
uint16 nControls;
AEERect rc;
uint32 dwProps;
uint16 wTitle;
uint16 wFocusID;
} DialogInfoHead;

成员：

wID | 对话框 ID（对话框的资源 ID）。
nControls | 控件数目。
rc | 对话框矩形。 默认设置为 (-1, -1, -1, -1)。
dwProps | 对话框属性。 当前，对话框仅支持 CP_BORDER 和 CP_3D_BORDER 控件参数。
wTitle | 对话框标题。 当前不支持此字段。
wFocusID | 启动对话框时激活的控件的 ID。

备注：

无

另请参阅：

AEERect

AEE 标准控件属性

返回数据结构列表

DialogItem

说明：

此结构包含对话框项目。

定义：

typedef structure
{
DialogItemHead h;
DListItem items[1];
} DialogItem;

成员：

h | 对话框项目题头。
items | 对话框列表项目数组。

备注：

无

另请参阅：

DListItem

返回数据结构列表

DialogItemHead

说明：

此结构用于定义对话框项目题头。

定义：

typedef structure
{
AEECLSID cls;
uint16 wID;
uint16 nItems;
uint32 dwProps;
uint16 wTextID;
uint16 wTitleID;
AEERect rc;
} DialogItemHead;

成员：

cls | 控件的 ClassID。
wID | 控件 ID（控件的资源 ID）。
nItems | 对话框列表项目数。
dwProps | 对话框控件属性。 （参见 CP_BORDER、CP_STATIC 等。）
wTextID | 文本字符串的资源 ID。
wTitleID | 标题字符串的资源 ID。
rc | 与对话框相关的矩形。 默认设置为 (-1, -1, -1, -1)。

备注：

无

另请参阅：

AEERect

AEECLSID 列表

返回数据结构列表

DIRECTORY_CHAR

说明：

此宏用于指定目录分隔字符。 由于 Windows 和设备上使用不同的字符，因而该宏可以帮助保持程序类属。另请注意，如果在应用程序中使用 '\ '，在设备上仍将用' /' 替换所有的' \'。

定义：

#ifdef AEE_SIMULATOR
#define DIRECTORY_CHAR '\\'
#else
#define DIRECTORY_CHAR '/'

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

DIRECTORY_STR

说明：

此宏用于指定目录分隔字符串。 由于 Windows 和设备上使用不同的字符串，因而该宏可以帮助保持程序类属。另请注意，如果在应用程序中使用 '\ '，在设备上仍将用' /' 替换所有的' \'。

定义：

#ifdef AEE_SIMULATOR
#define DIRECTORY_STR "\\"
#else
#define DIRECTORY_STR "/"

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

DListItem

说明：

此结构用于定义对话框列表项。

定义：

typedef structure _DListItem
{
uint16 wID;
uint16 wTextID;
uint16 wIconID;
uint16 pad;
uint32 dwData;
} DListItem;

成员：

wID | 对话框列表项 ID。
wTextID | 文本字符串资源 ID。
wIconID | 图标资源 ID。
pad | 保留。
dwData | 选择项目时与事件一起发送的 32 位数据。

备注：

无

另请参阅：

无

返回数据结构列表

FileAttrib

说明：

FileAttrib 用于指定文件的类型。

定义：

typedef enum
{
_FA_NORMAL=0,
_FA_HIDDEN=0x0001,
_FA_DIR=0x0002,
_FA_READONLY=0x0004,
_FA_SYSTEM=0x0008
} FileAttrib;

成员：

_FA_NORMAL | 文件为普通文件。
_FA_HIDDEN | 文件为隐藏文件（保留）。
_FA_DIR | 文件为目录（保留）。
_FA_READONLY | 文件为只读文件。
_FA_SYSTEM | 文件为系统文件。

备注：

无

另请参阅：

无

返回数据结构列表

FileInfo

说明：

FileInfo 包含与文件相关的信息。

定义：

typedef structure _FileInfo
{
FileAttrib attrib;
uint32 dwCreationDate;
uint32 dwSize;
char szName[MAX_FILE_NAME];
} FileInfo;

成员：

attrib | FileAttrib 指定的文件属性。
dwCreationDate | 文件创建日期。 1980 年 1 月 6 日 00:00:00 GMT 至今经过的时间。
dwSize | 文件大小。
szName | 文件名称。

备注：

无

另请参阅：

FileAttrib

返回数据结构列表

FileSeekType

说明：

使用 IFILE_Seek() 设置当前文件指针位置时，FileSeekType 用于指定查找操作的起点。

定义：

typedef enum {_SEEK_START, _SEEK_END, _SEEK_CURRENT} FileSeekType;

成员：

_SEEK_START | 从文件起始处开始查找。
_SEEK_END | 从文件末尾开始查找。
_SEEK_CURRENT | 从当前文件指针位置开始查找。

备注：

无

另请参阅：

无

返回数据结构列表

GetLine

说明：

该类型将被传递给 IGETLINE_GetLine 以保留行分析结果。

定义：

typedef structure GetLine
{
char * psz;
int nLen;
boolean bLeftover;
boolean bTruncated;
} GetLine;

成员：

psz | 指向以 NULL 结尾的解析行（不包括行终止符）的指针。
nLen | psz 的长度，psz 以 \0 结尾，但也可以包含 \0。
bLeftover | TRUE，如果是前一行的继续。
bTruncated | TRUE，如果不完整（超出读缓冲区空间，找不到行终止字符）。

备注：

无

另请参阅：

无

返回数据结构列表

HVFocusType

说明：

该代码用于标识引发 HVN_FOCUS 通知的焦点更改类型。

定义：

typedef enum {
HVFOCUS_NONE = 0
HVFOCUS_LINK,
HVFOCUS_EDIT,
HVFOCUS_CHECKBOX,
HVFOCUS_RADIO,
HVFOCUS_SUBMIT,
HVFOCUS_RESET,
HVFOCUS_LIST
} HVFocusType;

成员：

名称 | 含义
HVFOCUS_NONE | 无可见项目
HVFOCUS_LINK | <A HREF=...>
HVFOCUS_EDIT | <INPUT TYPE={TEXT|PASSWORD}> 或 <TEXTAREA>
HVFOCUS_CHECKBOX | <INPUT TYPE=CHECKBOX>： 状态 = 1/0（选中/未选中）
HVFOCUS_RADIO | <INPUT TYPE=RADIO>： 状态 = 1/0（选中/未选中）
HVFOCUS_SUBMIT | <INPUT TYPE=SUBMIT>
HVFOCUS_RESET | <INPUT TYPE=RESET>
HVFOCUS_LIST | <SELECT>

备注：

无

另请参阅：

无

返回数据结构列表

HViewFocus

说明：

此数据结构包含焦点更改信息，用于 HVN_FOCUS

通知。

定义：

typedef struct {
int posElem;
HVFocusType nType;
int nState;
} HViewFocus;

成员：

posElem
焦点项目的位置，无焦点项目时为 -1
nType
标识获得焦点的对象类型
int nState
复选框或单选控件的状态，仅用于 HVFOCUS_CHECKBOX 和 HVFOCUS_RADIO 焦点类型

备注：

无

另请参阅：

HVFocusType

返回数据结构列表

HViewJump

说明：

此数据结构包含超文本跳转和表单提交的信息， 用于 HVN_JUMP 和 HVN_SUBMIT 通知

定义：

typedef structure
{
int posElem;
const char * pszURL;
const char * pszMethod;
const char * pszData;
} HViewJump;

成员：

int posElem | 触发提交的 <FORM> 或 <A> 项目的位置
pszURL | HVN_JUMP | 超文本链接的 URL (URI)
pszMethod | HVN_SUBMIT | "GET"、"POST" 等。
pszData | HVN_SUBMIT | 对于 "GET" 为 NULL，否则为表单数据。

备注：

无

另请参阅：

HViewNotify

返回数据结构列表

HViewNotify

说明：

此数据结构包含通知信息，并通过引用传递给应用程序定义的通知回调函数。

定义：

typedef struct {
HVNotifyCode code;
IHtmlViewer * phv;
union {
HViewJump jump;
HViewJump submit;
int nDone;
HViewFocus focus;
} u;
} HViewNotify;

成员：

code
通知代码
IHtmlViewer * phv
标识发送通知的 IHtmlViewer
union u
联合具有以下成员
HViewJump jump
用于 HVN_JUMP
HViewJump submit
用于 HVN_SUBMIT
int nDone
用于 HVN_DONE
HViewFocus focus
用于 HVN_FOCUS

备注：

无

另请参阅：

HVNotifyCode

HViewFocus

IHTMLVIEWER_SetNotifyFn()

返回数据结构列表

HVNotifyCode

说明：

该枚举类型包含于传递至 PFNHVIEWNOTIFY 回调函数的 HViewNotify 结构中，用于指示通知类型。

定义：

typedef enum HVNotifyCode {

HVN_NONE = 0,

HVN_DONE,

HVN_JUMP,

HVN_SUBMIT,

HVN_FOCUS,

HVN_REDRAW_SCREEN,

HVN_FULLSCREEN_EDIT,

HVN_INVALIDATE

} HVNotifyCode;

成员：

名称含义

HVN_NONE | 未用值
HVN_DONE | 已完成加载（nDone = SUCCESS 或 ERROR）
HVN_JUMP | 用户选择的链接（使用 HViewNotify 结构的 'jump' 成员）
HVN_SUBMIT | 用户已提交表单（使用 HViewNotify 结构的 'submit' 成员）
HVN_FOCUS | 焦点已更改（使用 HviewNotify 结构的 'focus' 成员）
HVN_REDRAW_SCREEN | Htmlviewer 绘制绑定矩形外侧，小程序必须刷新其屏幕
HVN_FULLSCREEN_EDIT | Htmlviewer 编辑区域进入全屏幕模式
HVN_INVALIDATE | 需要刷新 Htmlviewer

另请参阅：

无

返回数据结构列表

HtmlViewer 选项 ID

说明：

这些常量用于获取和设置 IHtmlViewer 操作选项。 选项定义可按照类型分组，以帮助标识参数类型（转换成函数原型中的 HVOpt 类型）。

定义：

'integer' 类型选项
HVOPT_N_INDENT
基本缩进
HVOPT_N_VSPACE
基本段落间隔
HVOPT_N_SBWIDTH
滚动条宽度
HVOPT_N_ERROR
HVERR_... 标记（仅用于获取）
'RGBVAL' 类型选项
HVOPT_RGB_TEXT
默认的文本颜色
HVOPT_RGB_LINK
链接文本颜色
'char*' 类型选项
HVOPT_SZ_TYPE
MIME 类型和/或字符集（仅用于设置）
HVOPT_SZ_URL
基本 URL（仅用于设置）
'{interface}*' 类型选项
HVOPT_PTR_IWEB
IWeb 接口 Dox 用来获取子对象

备注：

以上选项 ID 常量用于 IHTMLVIEWER_SetOption() 和 IHTMLVIEWER_GetOption() 函数的 nID 参数。

另请参阅：

无

返回数据结构列表

HtmlViewer 属性标记

说明：

属性标记可启用 HTML 浏览器对象的特定行为。 属性标记可单独使用或组合使用。

定义：

HVP_SCROLLBAR
HTML 浏览器显示垂直滚动条
HVP_INLINE_EDIT
启用表单中的内联文本控件
HVP_INVALIDATION
启用 HVN_INVALIDATE 通知

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

IDC_COMMAND_RESERVED

说明：

它是一个占位符，用来指示在它上面的所有命令 ID 都被保留，以供 BREW 内部使用

定义：

#define IDC_COMMAND_RESERVED (0xff00)

成员：

无

备注：

它与控件发送的 EVT_COMMAND 联合使用

另请参阅：

EVT_COMMAND

返回数据结构列表

IDIB

说明：

此结构用于定义 BREW 设备无关位图格式。

定义：

OBJECT(IDIB) {
AEEVTBL(IDIB) *pvt;
IQueryInterface * pPaletteMap;
byte * pBmp;
uint32 * pRGB;
NativeColor ncTransparent;
uint16 cx;
uint16 cy;
int16 nPitch;
uint16 cntRGB;
uint8 nDepth;
uint8 nColorScheme ;
uint8 reserved[6];
}

成员：

pvt
指向 v 表的指针。 用户不能直接访问它，所有成员函数（IDIB_AddRef()、IDIB_Release() 和 IDIB_QueryInterface()）
均提供了宏进行访问。
pPaletteMap
已计算的调色板映射数据缓存。通常开发者可忽略此字段。 该成员提供读取 DIB 或写入 DIB 的图形操作。 一些算法（例如优化 DIB 到本地位块传输）包含复杂的初始化步骤，可将调色板数据转换成更易于访问的格式。 这些算法可将初始化数据存储到 pPaletteMap 中，以避免下次运行时需要重新计算。 要替换非 NULL 指针必须先释放之前已有的指针（使用 IQI_Release()），在删除 DIB 时，将释放所有非 NULL 指针。
pBmp
指向像素数组顶行的指针。
pRGB
指向调色板的指针。 调色板是 32 位颜色值的数组。 调色板数组的大小由 cntRGB 成员给定。 调色板定义了位图数据中像素值的意义。
像素值 N 对应着调色板中指针 N 处的颜色。 大于调色板大小的像素值均未定义。 调色板颜色值并非 RGBVAL 值， 并根据内存分布情况指定。 第一个字节为蓝色，第二个字节为绿色，第三个字节为红色，第四个字节则被忽略。 在低位优先的处理器上，调色板的值与 NTOHL(rgb) 相同。 在高位优先的处理器上，它与 RGBVAL 兼容。
ncTransparent
DIB 的透明色。 请注意，它不是 RGB 格式，而是指定为 NativeColor，直接对应于像素数组中的值。
cx
位图宽度（以像素为单位）。 必须避免读写大于或等于此索引的像素。
cy
位图高度（以像素为单位）。 必须避免读写大于或等于此索引的像素。
nPitch
从任意行到其下一行之间的偏移量。
cntRGB
调色板中的条目数。 如果此值为零，则位图中不包含调色板。 如果此值非零，则 pRGB 指向调色板条目的数组。
nDepth
每个像素的大小（以位为单位）。
nColorScheme
如果非零，则描述从像素值到 R-G-B 值的映射。 以下为当前已定义的 nColorScheme 值，它们描述了每个像素值中的位字段如何表示红色、绿色和蓝色强度
值
以下值为配色方案：
  • IDIB_COLORSCHEME_332
    • 3 位红色、3 位绿色、2 位蓝色
  • IDIB_COLORSCHEME_444
    • 4 位红色、4 位绿色、4 位蓝色
  • IDIB_COLORSCHEME_555
    • 5 位红色、5 位绿色、5 位蓝色
  • IDIB_COLORSCHEME_565
  • 5 位红色、6 位绿色、5 位蓝色
  • IDIB_COLORSCHEME_888:
    • 8 位红色、8 位绿色、8 位蓝色
在每种方案下，蓝色位都占用像素值的最低有效位，绿色位占用次高有效位，红色则占用最高有效位。 剩余的所有最高有效位均未使用。
reserved
保留字节以供未来版本使用。 构造 DIB 时，将这些位初始化为零；解析 DIB 时，忽略该值。

备注：

R-G-B 强度值与实际感知的颜色相关，但它们之间的精确关系非常复杂，并且依赖于显示器硬件。 IBitmap 和 IDIB 则无需考虑这些问题。

另请参阅：

NativeColor

IBitmap 接口, 函数列表

IDIB_QueryInterface()

IDIB_TO_IBITMAP()

返回数据结构列表

IDISPLAY 标记

说明：

这些常量用于在 IDISPLAY_DrawRect() 和 IDISPLAY_DrawText() 函数中构成标记（dwFlags 参数）。

定义：

矩形标记。

注意： IDF_RECT_INVERT 覆盖其它 IDF_RECT 标记。

IDF_RECT_NONE | 没有矩形，在 IDISPLAY_DrawText() 中使用。
IDF_RECT_FRAME | 绘制矩形边框。
IDF_RECT_FILL | 绘制填充矩形。
IDF_RECT_INVERT | 反转文本和背景颜色。
IDF_RECT_MASK | 隔离 IDF_RECT 标记的掩码。

文本水平对齐标记。

注意： 以下标记互相排斥。

IDF_ALIGN_NONE | 未指定对齐。
IDF_ALIGN_LEFT | 左对齐。
IDF_ALIGN_CENTER | 居中。
IDF_ALIGN_RIGHT | 右对齐。
IDF_ALIGN_FILL | 使用文本填充矩形宽度（由 IDISPLAY_DrawText() 指定）。
IDF_ALIGNHORZ_MASK | 隔离文本水平对齐标记的掩码。
IDF_ALIGN_TOP | 将文本与指定矩形的顶部对齐。
IDF_ALIGN_MIDDLE | 将文本放在指定矩形的中部。
IDF_ALIGN_BOTTOM | 将文本与指定矩形的底部对齐。
IDF_ALIGN_SPREAD | 将文本在矩形的高度内伸展。
IDF_ALIGNVERT_MASK | 隔离文本垂直对齐标记的掩码。
IDF_ALIGN_MASK (IDF_ALIGNHORZ_MASK|IDF_ALIGNVERT_MASK)

文本格式标记。

IDF_TEXT_UNDERLINE | 给文本加下划线。
IDF_TEXT_INVERTED | 反转文本（突出显示）。
IDF_TEXT_TRANSPARENT | 保留背景。
IDF_TEXT_FORMAT_OEM | 文本为 OEM_RAW_TEXT 格式 (byte *)。

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

IGRAPHICS 标记

说明：

这些位图标记用于控制许多 IGraphics 函数的行为。

定义：

AEE_GRAPHICS_NONE | 默认没有标记。
AEE_GRAPHICS_FRAME | 如果设置该标记，将绘制几何图元的边框。
AEE_GRAPHICS_CLEAR | 如果设置该标记，将使用背景色清除图形内部。
AEE_GRAPHICS_FILL | 如果设置该标记，将填充图形内部。

成员：

无

备注：

无

另请参阅：

IGRAPHICS_SetClip()

返回数据结构列表

ISocketCloser

说明：

此结构包含回调的函数指针和用户回调数据， 用于 ISocket_IOCtl。 当系统的其它部分需要套接字，而当前无可用套接字时，AEENet 将激活 ISocketCloser 回调。 如果打算使套接字在任意长的时间段内保持打开状态，最好指定此回调。

定义：

typedef structure ISocketCloser
{
PFNSOCKETCLOSE pfn;
void * pv;
} ISocketCloser

成员：

pfn | 请求所有者关闭套接字时调用的函数。
pv | 将作为第一参数传递给 pfn 的用户回调数据。

备注：

无

另请参阅：

ISOCKET_IOCtl()

PFNSOCKETCLOSE

返回数据结构列表

ISocketQI

说明：

要在不将 ISocket 修改为抽象类的情况下完成 QueryInterface，我们需要定义此结构，该结构可将通常传递给 QueryInterface 的参数打包。

定义：

typedef struct ISocketQI
{
AEECLSID clsId;
void *pif;
} ISocketQI

成员：

clsId | [input] | 由调用程序设置为所需的接口
pif | [output] | 如果请求的接口可用，则由 ISocket 设置为该接口；如果接口不可用或不支持调用，则设置为 0。

备注：

无

另请参阅：

ISOCKET_IOCtl(),

IQueryInterface

返回数据结构列表

ITField

说明：

时间控件中的字段。 每个时间控件中有三个字段。

定义：

typedef enum {ITF_HOUR, ITF_MIN, ITF_SEC} ITField;

成员：

ITF_HOUR | 时间控件中的小时字段。
ITF_MIN | 时间控件中的分钟字段。
ITF_SEC | 时间控件中的秒字段。

备注：

无

另请参阅：

无

返回数据结构列表

ITransform 属性

说明：

这些属性可用作 ITransform 函数的各种参数。

定义：

ITRANSFORM_TransformBltSimple 的 unTransform 参数使用的标记

TRANSFORM_FLIP_X 沿 x 轴翻转。

TRANSFORM_ROTATE_90 逆时针方向旋转 90 度。

TRANSFORM_ROTATE_180 逆时针方向旋转 180 度。

TRANSFORM_ROTATE_270 逆时针方向旋转 270 度。

TRANSFORM_SCALE_2 以 2 为系数放大。

TRANSFORM_SCALE_4 以 4 为系数放大。

TRANSFORM_SCALE_8 以 8 为系数放大。

TRANSFORM_SCALE_EIGHTH 以 1/8 为系数缩小。

TRANSFORM_SCALE_QUARTER 以 1/4 为系数缩小。

TRANSFORM_SCALE_HALF 以 1/2 为系数缩小。

ITRANSFORM_TransformBltSimple 和 ITRANSFORM_TransformBltComplex 的 unComposite 参数值

COMPOSITE_KEYCOLOR 执行透明位块传输。 这表示将不绘制源位图的透明色像素。

COMPOSITE_OPAQUE 不执行位块传输或非透明位块传输。

成员：

无

备注：

注意： 所有转换均使用源位图中心作为起点。

另请参阅：

ITRANSFORM_TransformBltSimple()

ITRANSFORM_TransformBltComplex()

IBITMAP_SetTransparencyColor()

返回数据结构列表

IVocoderConfigType

说明：

IVocoderConfigType 结构用于提供操作声码设备和提供/获取帧所需的信息。

定义：

typedef struct
{
void * usrPtr;
PFNREADY ReadyCB;
PFNDATA haveDataCB;
PFNDATA needDataCB;
PFNDATA playedDataCB;
uint32 watermark;
uint16 txReduction;
DataRateType max;
DataRateType min;
VocoderType vocoder;
boolean overwrite;
} IVocoderConfigType;

成员：

usrPtr | 回调中要传递回应用程序的用户数据。
readyCB | 在声码器使用就绪时调用的回调函数。
haveDataCB | 编码器有可用帧时调用的回调函数。
needDataCB | 解码器需要更多帧时调用的回调函数。
playedDataCB | 解码器已播放一帧以上时调用的回调函数。
watermark | 开始解码器声音路径之前要累积的帧计数。 输入和输出缓冲区以及 BREW 抖动的大小。
txReduction | 传输速率减小级别。
max | 编码器的最大数据速率。
min | 编码器的最小数据速率。
vocoder | 要使用的声码器算法。
overwrite | 编码器溢出时删除最新帧 (FALSE) 或最旧帧 (TRUE)。

备注：

无

另请参阅：

无

返回数据结构列表

IVocoderInfoType

说明：

IVocoderInfoType 结构用于向应用程序提供关于所选声码器模式的信息

定义：

typedef struct
{
uint16 frameDuration;
uint16 maxFrameSize;
} IVocoderInfoType;

成员：

frameDuration | 指示声码器帧的持续时间（以毫秒为单位）
maxFrameSize | 指示最大声码器帧的大小（以字节为单位）

备注：

无

另请参阅：

无

返回数据结构列表

JulianType

说明：

此结构包含儒略日期信息。

定义：

typedef structure
{
uint16 wYear;
uint16 wMonth;
uint16 wDay;
uint16 wHour;
uint16 wMinute;
uint16 wSecond;
uint16 wWeekDay;
} JulianType;

成员：

wYear | 4 位数年份。
wMonth | 1-12 月份（January 表示 1 月，December 表示 12 月）。
wDay | 1-31 日。
wHour | 0-23 时。
wMinute | 0-59 分。
wSecond | 0-59 秒。
wWeekDay | 星期值 0-6（0 表示星期一，6 表示星期日）。

备注：

无

另请参阅：

无

返回数据结构列表

NativeColor

说明：

NativeColor 类型用于表示位图中单个像素的值。 此值将解释成何种颜色取决于位图的格式。 如果为特定格式，则不能依赖这种值解释， 而应该使用 IBITMAP_NativeToRGB() 和 IBITMAP_RGBToNative() 来访问 NativeColor。

定义：

typedef uint32 NativeColor;

备注：

无

另请参阅：

IBITMAP_RGBToNative()

IBITMAP_NativeToRGB()

返回数据结构列表

NetMgrEvent

说明：

此类型用于枚举各种网络和套接字状态。 如果已经使用 INETMGR_OnEvent() 注册回调，则当网络或套接字状态发生更改时可获取这些状态。

定义：

typedef enum
{
NE_NONE,
NE_PPP,
NE_SO_OPENING,
NE_SO_CONNECTING,
NE_SO_CONNECTED,
NE_SO_CLOSING,
NE_SO_CLOSED
} NetMgrEvent;

成员：

NE_NONE | 无网络状态。
NE_PPP | PPP 连接状态已改变。
NE_SO_OPENING | 已打开套接字。
NE_SO_CONNECTING | 正在连接套接字。
NE_SO_CONNECTED | 已连接套接字。
NE_SO_CLOSING | 正在关闭套接字。
NE_SO_CLOSED | 已关闭套接字。

另请参阅：

PFNNETMGREVENT

INETMGR_OnEvent()

NetState

返回数据结构列表

NetSocket

说明：

NetSocket 用于枚举使用 INetMgr 接口能够创建的套接字类型。 NetSocket 值将传递给 INETMGR_OpenSocket()。

定义：

typedef enum {AEE_SOCK_STREAM=0, AEE_SOCK_DGRAM} NetSocket;

成员：

AEE_SOCK_STREAM | TCP： 流套接字。
AEE_SOCK_DGRAM | UDP： 数据报套接字。

备注：

无

另请参阅：

无

返回数据结构列表

NetState

说明：

NetState 用于枚举设备与因特网的 PPP 连接状态。 调用 INETMGR_NetStatus() 函数将返回 NetState 值。

定义：

typedef enum
{
NET_INVALID_STATE,
NET_PPP_OPENING,
NET_PPP_OPEN,
NET_PPP_CLOSING,
NET_PPP_CLOSED,
NET_PPP_SLEEPING,
NET_PPP_ASLEEP,
NET_PPP_WAKING,
} NetState;

成员：

NET_INVALID_STATE | 非实际状态，INETMGR_NetStatus() 不返回此值。
NET_PPP_OPENING | 正在建立 PPP 连接。
NET_PPP_OPEN | PPP 连接处于激活状态。
NET_PPP_CLOSING | PPP 连接正在关闭。
NET_PPP_CLOSED | PPP 连接处在非激活状态。
NET_PPP_SLEEPING | PPP 连接是“活动”的，但正在释放非 PPP 相关的网络资源（如 CDMA 通信量通道）
NET_PPP_ASLEEP | PPP 连接是“活动”的，但非 PPP 相关的网络资源已经释放
NET_PPP_WAKING | PPP 连接是“活动”的，并且正在重新获取非 PPP 相关的网络资源。

备注：

无

另请参阅：

INETMGR_NetStatus()

返回数据结构列表

OpenFileMode

说明：

OpenFileMode 用于在使用 IFILEMGR_OpenFile() 打开文件时指定文件的打开方式。

定义：

typedef enum
{
_OFM_READ=0x0001,
_OFM_READWRITE=0x0002,
_OFM_CREATE=0x0004,
_OFM_APPEND=0x0008,
_OFM_NO_BUFFER=0x8000
} OpenFileMode;

成员：

_OFM_READ | 以只读方式打开文件。
_OFM_READWRITE | 以读/写方式打开文件。
_OFM_CREATE | 以创建方式打开文件。
_OFM_APPEND | 以附加方式打开文件。
_OFM_NO_BUFFER | 禁用数据缓冲。

备注：

选项 _OFM_NO_BUFFER 在 BREW Emulator 中不起作用。

另请参阅：

无

返回数据结构列表

PFNAEEEVENT

说明：

PFNAEEEVENT 用于指定传递给 IDIALOG_SetEventHandler() 的事件回调类型。

定义：

typedef boolean (* PFNAEEEVENT)
(
void * pUser,
AEEEvent evt,
uint16 w,
uint32 dw
);

成员：

pUser | 用户数据。
evt | 事件代码。
w | 16 位事件特定参数。
dw | 32 位事件特定参数。

备注：

无

另请参阅：

IDIALOG_SetEventHandler()

返回数据结构列表

PFNCBCANCEL

说明：

此数据结构用于指定“取消”函数（可用来取消回调）的原型

定义：

typedef void (*PFNCBCANCEL)(AEECallback * pcb);

成员：

pcb
指向必须使用此函数取消的 AEECallback 的指针

备注：

它将与 AEECallback 一起使用

另请参阅：

AEECallback

返回数据结构列表

PFNCONNECTCB

说明：

PFNCONNECTCB 用于指定传递给 ISOCKET_Connect() 的回调函数类型。

定义：

typedef void (* PFNCONNECTCB)(void * pUser, int nError);

成员：

pUser | 用户数据。
nError | 错误代码。

备注：

无

另请参阅：

ISOCKET_Connect()

返回数据结构列表

PFNDATA

说明：

此数据类型用于为“具有数据”或“需要数据”的回调函数提供帧计数。
对于 haveDataCB，numFrames 是指队列中编码帧的数量。 对于 needDataCB，numFrames 是指在数据不可用时已收集的删除帧数。

定义：

typedef void (*PFNDATA)(uint16 numFrames, void * usrPtr);

成员

无

备注：

请注意，由于 BREW 延迟，这些数字反映的可能不是调用应用程序回调时的即时状况。 特别是 haveDataCB，在收到 AEE_VOC_EBUFFER_EMPTY 返回值之前，
它可能要继续读操作。

另请参阅：

无

返回数据结构列表

PFNHVIEWNOTIFY

说明：

该类型用于 HTML 浏览器通知回调函数。 通知回调由 HTML 浏览器调用，用于通知用户发生状态改变事件、用户生成的事件和其它事件。

定义：

typedef void (*PFNHVIEWNOTIFY)
(
void * pvUser,
HViewNotify * pHViewNotify
);

成员：

pvUser | 注册通知回调时与函数指针一起指定的 32 位值。
pHViewNotify | 指向说明通知的结构的指针。

备注：

无

另请参阅：

IHTMLVIEWER_SetNotifyFn()

返回数据结构列表

PFNIMAGEINFO

说明：

PFNIMAGEINFO 用于指定传递给 IIMAGE_Notify() 的回调函数类型。

定义：

typedef void (* PFNIMAGEINFO)
(
void * pUser,
IImage * pIImage,
AEEImageInfo * pi,
int nErr
);

成员：

pUser | 用户数据。
pIImage | 指向 IImage 接口对象的指针。
pi | 指向图像信息的指针。
nErr | 错误代码。

备注：

无

另请参阅：

IIMAGE_Notify()

AEEImageInfo

返回数据结构列表

PFNMEDIANOTIFY

说明：

PFNMEDIANOTIFY 是回调函数的类型说明，用户必须使用 IMedia 对象注册该回调函数。 IMedia 对象通过已注册的回调函数将全部事件和数据发送给用户。

定义：

typedef void (*PFNMEDIANOTIFY)
(
void * pUser,
AEEMediaCmdNotify * pCmdNotify
)

成员：

pUser | 用户指定的数据指针
pCmdNotify | 回调事件特定的信息

备注：

无。

另请参阅：

AEEMediaCmdNotify

返回数据结构列表

PFNMENUSORTCOMPARE

说明：

PFNMENUSORTCOMPARE 用于指定在 IMENUCTL_SortCustom() 中自定义排序所使用的比较函数。

定义：

typedef int (*PFNMENUSORTCOMPARE)
(
void * pUser,
uint32 dwData1,
uint32 dwData2
);

成员：

pUser | 用户数据。
dwData1 | DataItem1。
dwData2 | DataItem2。

备注：

此例程必须比较元素，然后返回以下值之一：

< 0，如果 DataItem1 小于 DataItem2。

= 0，如果 DataItem1 等于 DataItem 2。

> 0，如果 DataItem1 大于 DataItem 2。

另请参阅：

IMENUCTL_SortCustom()

返回数据结构列表

PFNNETMGREVENT

说明：

PFNNETMGREVENT 是网络事件回调函数的原型。 在使用 INETMGR_OnEvent() 函数注册事件后，当套接字或网络上发生网络事件时将调用它。

定义：

typedef void (*PFNNETMGREVENT)
(
void * pUser,
NetMgrEvent evt,
uint32 dwData
);

成员：

pUser | 用户特定数据。
evt | 触发该回调的事件。
dwData | 调用程序传递的数据，取决于导致回调的事件。

备注：

根据 evt 的值，dwData 具有不同的含义。 下面将按 evt： dwData 的顺序给出这些含义。

NE_PPP | NetStatus
NE_SO_OPENING | ISocket *
NE_SO_CONNECTING | ISocket *
NE_SO_CONNECTED | ISocket *
NE_SO_CLOSING | ISocket *
NE_SO_CLOSED | ISocket *

另请参阅：

INETMGR_OnEvent()

NetMgrEvent.

返回数据结构列表

PFNNOTIFY

说明：

PFNNOTIFY 用于指定数据类型（指向函数类型的函数指针）

void foo(void * pData)..

定义：

typedef void (* PFNNOTIFY)(void * pData);

成员：

无

备注：

无

另请参阅：

无

返回数据结构列表

PFNPOSITIONCB

说明：

PFNPOSITIONCB 用于指定传递给 ISHELL_GetPosition() 的回调函数类型。

定义：

typedef void (* PFNPOSITIONCB)
(
void * pUser,
AEEPositionInfo * pli,
int nErr
);

成员：

pUser | 用户数据。
pli | 定位信息。
nErr | 错误代码。

备注：

无

另请参阅：

AEEPositionInfo

ISHELL_GetPosition()

返回数据结构列表

PFNRINGEREVENT

说明：

PFNRINGEREVENT 用于指定使用 IRINGERMGR_RegisterNotify() 注册的通知函数类型。

定义：

typedef void (* PFNRINGEREVENT)
(
void * pUser,
AEERingerEvent evt,
uint32 dwParm,
int nErr
);

成员：

pUser
用户数据。
evt
指定通知原因的事件。
dwParm
包含事件特定的信息。
nErr
错误代码：
  • 如果成功，则为 AEE_SUCCESS。
  • 否则为错误代码

此处为发送的各种通知及其事件特定的参数：

ARE_PLAY： 完成播放或调用 IRINGERMGR_stop 时发送。

dwparam = 0。

如果播放仍在继续，则 nErr 为 EINCOMPLETEITEM。

如果播放已完成，则 nErr 为 0

ARE_CREATE： 完成创建振铃器或出错时发送。

dwParam 包含振铃器 id。

nErr： AEE_SUCCESS 或 EFAILED

ARE_WRITE： 每当发生振铃器文件写操作时发送。

dwParam： 写入文件的字节数。

nErr 将设置为 AEE_SUCCESS

备注：

无

另请参阅：

AEERingerEvent

IRINGERMGR_RegisterNotify()

返回数据结构列表

PFNSMSSTATUS

说明：

它是通知函数的原型，如果应用程序要了解刚刚发送的 MO-SMS 的状态，则必须将该函数原型的地址传递给 ITAPI_SendSMS()。 使用 ITAPI_SendSMS() 发送 SMS 消息时，BREW 将调用此通知函数把消息发送的状态告知应用程序。

定义：

typedef void (*PFNSMSSTATUS)(void * pUser, int16 status);

成员：

pUser | BREW 调用后传递回通知函数的用户特定数据。
status | 消息发送的状态。 可设置为 SUCCESS（成功）或 EFAILED（失败）。

备注：

无

另请参阅：

ITAPI_SendSMS()

返回数据结构列表

PFNSOCKETCLOSE

说明：

PFNSOCKETCLOSE 是 ISocketCloser 回调的原型。 调用它建议 ISocket 的所有者将其释放，以便 ISocket API 的其它客户机继续执行（如果可以）。

定义：

typedef void (* PFNSOCKETCLOSE)(void * pvCxt, ISocket * pSocket);

成员：

pvCxt | ISocketCloser 中指定的用户数据
pSocket | 相关套接字（如果可以，请释放该套接字）

备注：

无

另请参阅：

ISocketCloser

返回数据结构列表

PFNSOUNDPLAYERSTATUS

说明：

PFNSOUNDPLAYERSTATUS 是 ISoundPlayer 回调函数类型说明，应用程序必须使用 ISoundPlayer 注册。 ISoundPlayer 通过已注册的回调函数将全部事件和数据发送给应用程序。

定义：

typedef void (* PFNSOUNDPLAYERSTATUS)
(
void * pUser,
AEESoundPlayerCmd eCBType,
AEESoundPlayerStatus eSPStatus,
uint32 dwParam
);

成员：

pUser | 应用程序特定的数据指针。
eCBType | 回调类型。
eSPStatus | 回调类型内的状态。
dwParam | 指向 AEESoundPlayerCmdData 的指针（如果有）。 否则为 NULL。

备注：

无

另请参阅：

AEESoundPlayerCmd

AEESoundPlayerStatus

返回数据结构列表

PFNSOUNDSTATUS

说明：

PFNSOUNDSTATUS 是应用程序必须使用 ISound 注册的 ISound 回调函数的类型定义。 ISound 通过已注册的回调函数将全部事件和数据发送给应用程序。

定义：

typedef void (* PFNSOUNDSTATUS)
(
void * pUser,
AEESoundCmd eCBType,
AEESoundStatus eSPStatus,
uint32 dwParam
);

成员：

pUser | 应用程序特定的数据指针。
eCBType | 回调类型。
eSPStatus | 回调类型内的状态。
dwParam | 指向 AEESoundCmdData 的指针（如果有）。 否则为 NULL。

备注：

无

另请参阅：

AEESoundCmd

AEESoundStatus

AEESoundCmdData

返回数据结构列表

PFNWEBHEADER

说明：

它是用于 web 头信息的回调原型。 如果已指定，则只要 IWeb 接口 对象解析了应答中的头信息，就会调用此函数。 它将作为 IWEBOPT_HEADERHANDLER pVal 传递给 IWEB_AddOpt() 或 IWEB_GetResponse()。

定义：

typedef void (* PFNWEBHEADER)
(
void * pNotifyData,
const char * pszName,
GetLine * pplVal
);

成员：

pNotifyData | 用户提供的回调上下文。 使用 IWEBOPT_HANDLERDATA 指定。
pszName | 经过解析的头信息名称（以 NULL 结尾，没有冒号），如“内容场±取薄
pplVal | 头信息值。 有关 GetLine 的定义，请参阅 AEESource.h。

备注：

由于 IWeb 的内部缓冲区不一定能够容纳一行，因此 pplVal 可能被截断或包含其它行的剩余字符。 如果发生这种情况，将在每次收到头信息数据包时激活头信息回调。 第一个回调将把 pszName 设置为头信息的名称；所有后续回调将把 pszName 设置为 NULL。

另请参阅：

GetLine

WebOpt

PFNWEBSTATUS

返回数据结构列表

PFNWEBSTATUS

说明：

它是 web 请求状态的回调原型，将作为 IWEBOPT_STATUSHANDLER pVal 传递给 IWEB_AddOpt() 或 IWEB_GetResponse()。

定义：

typedef void (* PFNWEBSTATUS)
(
void * pNotifyData,
WebStatus ws,
void * pData
);

成员：

pNotifyData | 用户提供的回调上下文，使用 IWEBOPT_HANDLERDATA 指定。
ws | 正在交换的状态。
pData | 其它数据，因尚未使用，故应忽略不计。

备注：

PFNWEBSTATUS 和 PFNWEBHEADER 类型使用相同的 pNotifyData 值。

另请参阅：

WebStatus

返回数据结构列表

PhoneState

说明：

PhoneState 用于 ITAPI_GetStatus()，以获取设备的当前状态。 它是 TAPIStatus 数据结构中的一个成员，该结构将由 ITAPI_GetStatus() 函数填充。

定义：

typedef enum
{
PS_OFFLINE,
PS_IDLE,
PS_INCOMING,
PS_ORIG,
PS_CONVERSATION
} PhoneState;

成员：

PS_OFFLINE | 设备处于离线状态。
PS_IDLE | 设备处于空闲状态。
PS_INCOMING | 设备上存在进入呼叫。
PS_ORIG | 设备正在发起呼叫。
PS_CONVERSATION | 设备正在通话中。

备注：

无

另请参阅：

TAPIStatus

返回数据结构列表

RESBLOB_DATA

说明：

此宏用于获取 AEEResBlob 中指向原始数据的指针。

定义：

RESBLOB_DATA(b) ((void *)((byte *)(b) + b->bDataOffset))

参数：

b
AEEResBlob 对象

评估值：

指向 blob 数据的 void *

备注：

无

另请参阅：

AEEResBlob

ISHELL_LoadResData()

ISHELL_LoadResDataEx()

返回数据结构列表

ResType

说明：

该 ENUM 用于指定识别资源文件资源的资源类型。

定义：

typedef enum
{
RESTYPE_STRING=1,
RESTYPE_IMAGE=6,
RESTYPE_DIALOG=0x2000,
RESTYPE_CONTROL=0x2001,
RESTYPE_LISTITEM=0x2002,
RESTYPE_BINARY=0x5000
} ResType;

成员：

RESTYPE_STRING | 字符串资源，由 UNICODE 或 ISOLATIN 字符串构成。
RESTYPE_IMAGE | 图像资源，由 BMP、PNG 或其它图像构成。
RESTYPE_DIALOG | 对话框资源，由一个或多个对话框控件构成。
RESTYPE_CONTROL | 控件资源。
RESTYPE_LISTITEM | 列表项类型资源。
RESTYPE_BINARY | 二进制数据资源。

备注：

无

另请参阅：

ISHELL_LoadResString()

返回数据结构列表

RGBVAL

说明：

此数据类型用于定义颜色的 RGB 值。 32 位数据中红、绿、蓝各占 8 位，如下所示：

保留位使用零来填充。

定义：

typedef uint32 RGBVAL

成员：

无

备注：

用户可使用 MAKE_RGB 宏设置红、绿和蓝值，以获取相应的 RGBVAL，创建自己的颜色。

另请参阅：

无

返回数据结构列表

SockIOBlock

说明：

此结构用于说明可从中读写数据的独立内存块。

调用 ISOCKET_ReadV() 和 ISOCKET_WriteV() 时将使用 SockIOBlock 结构数组，
用于说明作为连续流发送或接收的数据(即使这些数据在内存中是分散在若干块中)。

定义：

typedef structure
{
byte * pbBuffer;
uint16 wLen;
} SockIOBlock;

成员：

pbBuffer | 数据缓冲区。
wLen | 缓冲区长度。

备注：

无

另请参阅：

无

返回数据结构列表

Sprite 属性

说明：

这些属性应用于 AEESpriteCmd 结构中的每个 sprite。

定义：

SPRITE_SIZE_8X8 |
SPRITE_SIZE_16X16 |
SPRITE_SIZE_32X32 |
SPRITE_SIZE_64x64 |
SPRITE_SIZE_MAX | Sprite 大小，用于 unSpriteSize 字段。
SPRITE_SIZE_END | unSpriteSize 用来提示命令数组结束的特殊值。
SPRITE_FLIP_X |
SPRITE_FLIP_Y |
SPRITE_ROTATE_90 |
SPRITE_ROTATE_180 |
SPRITE_ROTATE_270 |
SPRITE_SCALE_2 |
SPRITE_SCALE_4 |
SPRITE_SCALE_8 |
SPRITE_SCALE_EIGHTH |
SPRITE_SCALE_QUARTER |
SPRITE_SCALE_HALF | unTransform 字段的简单变换标记。 这些标记可以组合使用。 要组合翻转和旋转，请将这两个值进行异或运算 （通过 SPRITE_FLIP_X | SPRITE_ROTATE_180 即可实现 SPRITE_FLIP_Y）。
SPRITE_MATRIX_TRANSFORM | 此标记用于 unTransform，并通过 unMatrixTransform 字段指定应执行复杂转换。 设置此标记后，将忽略 unTransform 中的其它所有标记。
SPRITE_LAYER_0 |
SPRITE_LAYER_1 |
SPRITE_LAYER_2 |
SPRITE_LAYER_3 |
SPRITE_LAYER_HIDDEN | unLayer 字段的有效层。

成员：

无

备注：

注意：所有转换均使用 sprite 中心作为起点。

另请参阅：

AEESpriteCmd

返回数据结构列表

SSLInfo

说明：

此数据类型是包含安全 ISocket 的 SSL 协商的结果。

定义：

typedef struct SSLInfo
{
int nResult;
SSLSecurityInfo SecInfo;
X509TrustResult TrustResult;
ISocket *pSSLSocket;
}SSLInfo;

成员：

nResult | SSL 协商的常规结果。 SSL_RESULT_* 之一
SecInfo | 协商的安全级别。 对于 SSL_RESULT_SECURED 有效
TrustResult | 信任结果；请参阅 AEEX509Chain.h
pSSLSocket | 代表安全流的打开套接字

备注：

该数据类型返回协商结果。 结果包括两部分，协议协商结果和 X509 链验证的信任结果。 如果 nResult 为 SSL_RESULT_TRUST_ERR，则应检查 TrustResult 以获取详细信息。 通常，可以覆盖信任错误。由于 pSSLSocket 为安全流，因此它是结果中最重要的部分。

另请参阅：

ISSL_Negotiate()

SSLSecurityInfo

IX509CHAIN_Verify()

X509TrustResult

返回数据结构列表

SSLSecurityInfo

说明：

此数据类型是包含密码组的已协商 SSL 安全级别。

定义：

typedef struct
{
uint16 uProtoVersion;
uint8 uKeyExchange;
uint8 uCryptAlgo;
uint8 uHashAlgo;
uint16 uCipherSuite;
}SSLSecurityInfo;

成员：

uProtoVersion | 已协商的 SSL 协议版本。 SSL_VERSION_* 之一
uKeyExchagne | 密钥交换算法。 SSL_KEYPROT_* 之一
uCryptAlgo | 已协商的对称算法。 SSL_CRYPT_* 之一
uHashAlgo | 已协商的散列函数。 SSL_HASH_* 之一
uCipherSuite | 已协商的密码组。 SSL_CSUITE_* 之一

备注：

它可以将在 SSLSecurityInfo 数据结构中报告当前会话的已协商安全级别。

以下常量用于定义协议版本。 不支持 2 版 SSL。

SSL_VERSION_30 SSL 3.0 版

SSL_VERSION_TLS10 TLS 1.0 版

SSL_VERSION_UNKNOWN 未知协议

以下常量用于定义密钥交换/协议/保护方案或算法。 请注意，对于特定版本 Brew 或特定手持设备，这些算法可能不全可用。

SSL_KEYPROT_NONE 无密钥交换

SSL_KEYPROT_DH_ANONYMOUS 匿名 Diffie-Hellman 算法

SSL_KEYPROT_DH_EPHEMERAL 临时 Diffie-Hellman 算法

SSL_KEYPROT_DH_DSS_SIGN 带 DSS 签名的 Diffie-Hellman 算法

SSL_KEYPROT_DH_DSS_SIGN 带 RSA 签名的 Diffie-Hellman 算法

SSL_KEYPROT_DH_DSS_CERT 带 DSS 证书的 Diffie-Hellman 算法

SSL_KEYPROT_DH_RSA_CERT 带 RSA 证书的 Diffie-Hellman 算法

SSL_KEYPROT_RSA 带证书的标准 RSA 算法

SSL_KEYPROT_UNKNOWN 交换内容未知

以下常量用于定义所使用的对称密码。 请注意，此处定义的常量并不表示特定版本的 Brew 或手持设备支持它。 ARC4 通常始终可用，且运行良好。 它也是密码组中的算法，将其分离只是为了方便使用。

SSL_CRYPT_NONE 未加密

SSL_CRYPT_RC4 ARC4 算法

SSL_CRYPT_DES DES 算法

SSL_CRYPT_3DES 3DES 算法

SSL_CRYPT_UNKNOWN 所用的算法未知

以下常量用于定义所使用的散列函数。 它们通常可用于所有 Brew 版本或手持设备。

SSL_HASH_NONE 无散列函数

SSL_HASH_SHA SHA-1 散列函数

SSL_HASH_MD5 MD5 散列函数

SSL_HASH_UNKNOWN 所用的散列函数未知

以下常量用于指示所使用的密码组。 它与上述常量集稍有冗余，但包含它可提供方便。 给定版本的 Brew 或给定的手持设备并不一定支持所有密码组。 这些常量对应于 SSL 和 TLS 的标准密码组。

SSL_CSUITE_RSA_WITH_RC4_128_MD5

SSL_CSUITE_RSA_WITH_RC4_128_SHA

SSL_CSUITE_RSA_WITH_DES_CBC_SHA

SSL_CSUITE_RSA_WITH_3DES_EDE_CBC_SHA

SSL_CSUITE_UNKNOWN

以上常量还可用于在协商之前请求特定的协议

版本集和密码组。

另请参阅：

ISSL_Negotiate()

返回数据结构列表

TAPIStatus

说明：

TAPIStatus 用于 ITAPI_GetStatus() 中以获取设备当前的 TAPI 状态。 如果应用程序已注册 TAPI 状态通知，它还将作为 EVT_NOTIFY 事件的 dwParam 成员发送。

定义：

typedef structure
{
char szMobileID[MOBILE_ID_LEN +1];
PhoneState state;
flg bData:1;
flg bDigital:1;
flg bRoaming:1;
flg bCallEnded:1;
flg bE911CallbackMode:1;
flg bRestricted:1;
flg bRegistered:1;
flg bDormancy:1;
} TAPIStatus;

成员：

szMobileID | 手机 ID（数字）。
state | 当前设备状态。 这是一个类型的枚举
bdata | 指示设备是否处于数据呼叫状态。
bDigital | 指示设备是否处于数字服务状态。
bRoaming | 指示设备是否处于漫游状态。
bCallEnded | 指示该通知是否作为通话结束的一部分发送。 如果应用程序已注册为对任何更改接收更新的 TAPIStatus 信息通知，则此标记将非常有用。 通过 ISHELL_RegisterNotify() 函数可完成通知注册。
bE911CallbackMode | 指示设备是否处于 E911 回调模式。
bRestricted | 未使用该成员。
bRegistered | 系统注册已完成，如果不可用，则设置为 TRUE。
bDormancy | 网络完全支持休眠，如果不可用，则为 FALSE。

备注：

无

另请参阅：

PhoneState

ITAPI_GetStatus()

返回数据结构列表

TChType

说明：

TChType 用于枚举 GETCHTYPE() 函数返回的宽字符类型。

定义：

typedef enum
{
SC_UNKNOWN,
SC_ALPHA,
SC_DIGIT,
SC_WHITESPACE
} TChType;

成员：

SC_UNKNOWN | 未知类型。
SC_ALPHA | 字母类型。
SC_DIGIT | 数字类型 (0-9)。
SC_WHITESPACE | 空白。

备注：

无

另请参阅：

GETCHTYPE()

返回数据结构列表

Tile 贴图属性

说明：

这些属性将应用于 AEETileMap 结构中的每个 tile 贴图。

定义：

TILE_SIZE_8X8 |
TILE_SIZE_16X16 |
TILE_SIZE_32X32 |
TILE_SIZE_64X64 | unTileSize 字段的值。
MAP_FLAG_WRAP | unFlags 字段的标记。 （当前唯一标记。） 如果已设置 MAP_FLAG_WRAP，则应上卷映射。 例如，如果映射宽度为 16 tile，则 0 列应在 15 列后显示。
MAP_SIZE_1 |
MAP_SIZE_2 |
MAP_SIZE_4 |
MAP_SIZE_8 |
MAP_SIZE_16 |
MAP_SIZE_32 |
MAP_SIZE_64 |
MAP_SIZE_128 |
MAP_SIZE_256 |
MAP_SIZE_512 |
MAP_SIZE_1024 | 宽度和高度字段的值。

备注：

无

另请参阅：

AEETileMap

返回数据结构列表

Tile 属性

说明：

这些标记将应用于 AEETileMap 的 pMapArray 数组字段元素中的每个 tile。

定义：

TILE_FLIP_X | 沿 X 轴翻转 tile。
TILE_FLIP_Y | 沿 Y 轴翻转 tile。 （注意：它是 FLIP_X 和 ROTATE_180 的组合）。
TILE_ROTATE_90 | 沿逆时针方向旋转 tile 90 度。
TILE_ROTATE_180 | 沿逆时针方向旋转 tile 180 度。
TILE_ROTATE_270 | 沿逆时针方向旋转 tile 270 度。
TILE_TRANSPARENT | 透明绘制 Tile。
TILE_INDEX_MASK | 用于 tile 索引的位掩码。
TILE_INDEX_NOTHING | 此特殊指针值表示不绘制 tile 的任何内容。 它在功能上等同于位块传输一个完全透明的 tile，但其速度较快。

成员：

无

备注：

无

另请参阅：

AEETileMap

返回数据结构列表

UrlParts

说明：

URL 字符串的一组字符串指针，解析为 URL 中最有用的部分。
由 IWebUtil_ParseUrl() 构造，仅用于以 NULL 结尾的字符串。

定义：

typedef structure UrlParts
{
const char * cpcSchm;
const char * cpcAuth;
const char * cpcUser;
const char * cpcPass;
const char * cpcHost;
const char * cpcPort;
const char * cpcPath;
const char * cpcSrch;
const char * cpcName;
const char * cpcEnd;
} UrlParts;

成员：

cpcSchm | 始终指向字符串的开始处。
cpcAuth | 指向 URL 的 "//..." 部分（如果存在）。
cpcUser | 指向 "user:pwd@host:port/..."（如果存在）。
cpcPass | 指向 ":pwd@host:port/..."。
cpcHost | 指向 "host:port/..."。
cpcPort | 指向 ":port/..."。
cpcPath | 指向 '/'（如果存在）。
cpcSrch | 指向 '?'（如果存在）。
cpcName | 指向 '#'（如果存在）。
cpcEnd | 指向 '\0'。

备注：

如果字段不存在，则其值与下一个成员的值相同。 例如 mailto:brew@qualcomm.com，由于没有 "//"，因此 cpcAuth 被设为 cpcUser（下一个成员），而 cpcUser 指向 "brew@..."。

下面的 UP_ macros 将有助于轻松地使用 URL。

UP_HASSCHM(pup) | TRUE，如果 URL 指定一个资源类型（在第一个斜杠前， 但不在位置 0 处有一个冒号）。
UP_SCHMLEN(pup) | 资源类型的长度，包括结尾的 ':'。
UP_HASAUTH(pup) | TRUE，如果 URL 包含权限部分，包括用户、密码、主机和端口（如果适用）。
UP_AUTHLEN(pup) | 权限部分的长度（包括前导 ì//）°
UP_HASHOST(pup) | TRUE，如果 URL 包含主机部分。
UP_HOSTLEN(pup) | 主机部分的长度。
UP_HASPORT(pup) | TRUE，如果 URL 包含端口部分（在主机上）。
UP_PORTLEN(pup) | 端口部分的长度（包括 :í）°
UP_HASUSER(pup) | TRUE，如果 URL 指定一个用户。
UP_HASPASS(pup) | TRUE，如果 URL 指定一个密码（包括前导 :í 和后缀 @í°
UP_HASPATH(pup) | TRUE，如果 URL 包含路径部分（主机后的第一个 /í，如°有）°
UP_PATHLEN(pup) | 路径部分的长度（包括 /í）°
UP_HASSRCH(pup) | TRUE，如果 URL 包含搜索部分（?í 后的信息）。
UP_SRCHLEN(pup) | 搜索部分的长度（包括 ?í）°
UP_HASNAME(pup) | TRUE，如果 URL 包含命名位置。
UP_NAMELEN(pup) | 命名位置部分的长度（包括 #í）°
UP_URLLEN(pup) | 整个 URL 的长度（不包括 Null 终止符）。

示例 2：

cpszUrl = "http://user:pass@host:port/path/doc.htm?srch#name"
cpcSchm = "http://use...
cpcAuth = "//user:pas...
cpcUser = "user:pass@...
cpcPass = ":pass@host...
cpcHost = "host:port/...
cpcPort = ":port/path...
cpcPath = "/path/doc....
cpcSrch = "?srch#name...
cpcName = "#name"
cpcEnd = ""

示例 3：

cpszUrl = "http://user@host/path#name
cpcSchm = "http://use...
cpcAuth = "//user@hos...
cpcUser = "user@host/...
cpcPass = "host/path#...
cpcHost = "host/path#...
cpcPort = "/path#name"
cpcPath = "/path#name"
cpcSrch = "#name"
cpcName = "#name"
cpcEnd = ""

示例 4：

cpszUrl = "mailto:brewery@qualcomm.com
cpcSchm = "mailto:bre...
cpcAuth = "brewery@qu...
cpcUser = "brewery@qu...
cpcPass = "brewery@qu...
cpcHost = "brewery@qu...
cpcPort = "brewery@qu...
cpcPath = "brewery@qu...
cpcSrch = ""
cpcName = ""
cpcEnd = ""

另请参阅：

无

返回数据结构列表

WebFormField

说明：

此数据类型通常是一个以 NULL 结尾的字符串，表示表单字段的名称和值。

定义：

typedef struct WebFormField
{
char *pcName;
char *pcValue;
} WebFormField;

成员：

char *pcName | 指向名称开始处的指针
char *pcValue | 指向值开始处的指针

备注：

如果将 WEBUTIL_PFFF_NOMUTATE 传递给 IWEBUTIL_ParseFormFields()，
则 WebFormField 结果中的指针将指向重叠的字符串。

例如： 假定字符串 "x=y"，则 pcName 将指向 "x=y"，pcValue 将指向 "y"。

另请参阅：

IWEBUTIL_ParseFormFields()

返回数据结构列表

WebOpt

说明：

该结构用于保存 IWebOpts 的 ID/值对。

定义：

typedef structure WebOpt
{
int nId;
void * pVal;
} WebOpt;

成员：

nId | 选项 ID，选择在 AEEWeb.h 中定义的一个 WEBOPT_ *。
pVal | 取决于 nId 的选项值。

备注：

WebOpt 结构是与 IWeb 接口交流的基本通信构建块。 使用 IWEB_AddOpt() 时，将不复制 WebOpt 结构，但结构内的选项 ID 列表和索引均可用。

另请参阅：

WebOpts 列表

IWEBOPTS_AddOpt()

返回数据结构列表

WebRespInfo

说明：

WebRespInfo 用于简化最基本的 Web 处理编码，并保留如何进行 Web 处理的最易见和重要的信息。

定义：

typedef structure
{
int nCode;
ISource * pisMessage;
long lContentLength;
const char * cpszContentType;
const char * cpszCharset;
int32 tExpires;
int32 tModified;
} WebRespInfo;

成员：

nCode | 协议错误代码或负的 WEB_ERROR（有关代码，请参阅 AEEError.h）。 可使用 WEB_ERROR_MAP(nCode) 映射 AEE 错误，并使用 WEB_ERROR_SUCCEEDED(nCode) 测试是否成功。 正的错误代码由服务器返回；负的错误代码则指示系统错误。
pisMessage | 表示应答正文的流。
lContentLength | 正文流的长度，如果已知（若未知，则为 -1）。 没有必要限制从 pisMessage 中读取，IWeb 将确保 EOF 正确。
cpszContentType | 消息的 Mime 类型，如果已知（否则为 NULL）。
cpszCharset | 消息的字符集，如果已知（否则为 NULL）。
tExpires | 文档到期日，如果已知（否则为 -1）。
tModified | 文档修改日，如果已知（否则为 -1）。

备注：

只有调用 IWEBRESP_Release() 后，cpszContentType 和 cpszCharset 所指向的内存才会有效。 类似地，释放 IWebResp 接口也将释放 pisMessage。 如果要在释放 IWebResp 接口后读取 pisMessage，则必须调用 IWEBRESP_AddRef() 才能访问 pisMessage。

另请参阅：

无

返回数据结构列表

WebStatus

说明：

传递给 WebStatus 回调的类型，以通知 API 客户端有关进行中的 Web 请求状态。

这些类型为预定义的状态事件。

定义：

typedef enum WebStatus
{
WEBS_STARTING = 0,
WEBS_CANCELLED,
WEBS_GETHOSTBYNAME,
WEBS_CONNECT,
WEBS_SENDREQUEST,
WEBS_READRESPONSE,
WEBS_GOTREDIRECT,
WEBS_CACHEHIT
} WebStatus;

成员：

WEBS_STARTING | 初始值。
WEBS_CANCELLED | 被 CALLBACK_Cancel 取消。
WEBS_GETHOSTBYNAME | 正在 URL 中查找主机名。
WEBS_CONNECT | 正在连接至主机。
WEBS_SENDREQUEST | 正在发送请求数据。
WEBS_READRESPONSE | 正在接收应答数据。
WEBS_GOTREDIRECT | 正在处理 HTTP 重定向。
WEBS_CACHEHIT | 在缓存中找到文档。

备注：

无

另请参阅：

无

返回数据结构列表

X509BasicCert

说明：

基本证书信息

定义：

typedef struct X509BasicCert
{
uint32 uTrustOverrideID;
uint32 uSigAlgID;
uint32 uStartValidity;
uint32 uEndValidity;
X509RSAKey Key;
uint8 uVersion;
}X509BasicCert;

成员：

uTrustOverrideID | 用于信任覆盖记录的整型 ID
uSigAlgID | 用于签署证书的签名类型 （不是证书中的密钥类型）。
uStartValidity | 证书的生效日（按 GPS 时间计算）
uEndValidity | 到期日（按 GPS 时间计算）
Key | 证书中的密钥。
uVersion | 证书的版本。 值 2 表示 3 版。

备注：

该结构大约 40 字节，因此可以在堆栈上实现。 它包含小证书中的全部字段。

另请参阅：

IX509CHAIN_GetRSAKey()

返回数据结构列表

X509CertPart

说明：

用于提供获取证书部分的结果

定义：

typedef struct X509CertPart
{
unsigned int uLength;
const uint8 *pcValue;
const uint8 *pcRawOID;
uint32 uASNOID;
boolean bCriticallity;
uint8 uASN1Type;
uint8 uRDNIndex;
int nNumInstances;
}X509CertPart;

成员：

uLength | 指该部分的长度。
pcValue | 指向实际部分的指针（只要存在 IX509Chain，指针就会保持指向实际部分）
pcRawOID | 指向始于 OID 类型的未解析 OID
uASNOID | 如果已知，则为 OID 的已解析值。 请参阅 ASNOID 定义。
bCriticality | 只用于 v3 扩展，如果是关键扩展则为真。
uASN1Type | AEEASN1OIDs.h 中值的数据类型，例如 ASN1_PRINTABLE_STRING_TYPE。
uRDNIndex | 它在 DN 中对 RDN 进行计数。如果在第一个 RDN 中找到该部分，则其值为 0。对于扩展，其值始终为 0
nNumInstances | 此字段中该 OID 的实例数目

备注：

该结构大约 20 字节，因此可以在堆栈上实现。 它用于指向 DN 部分（名称各不相同）或指向 X.509 v3 扩展。 尽管语义上不相关，但它们的表示和获取方式类似。

另请参阅：

IX509CHAIN_GetFieldPart()

X509PartRequest

返回数据结构列表

X509PartRequest

说明：

用于指定要获取证书字段的哪些部分

定义：

typedef struct X509PartRequest
{
int32 nCertWebOpt;
int32 nCertIndex;
uint8 uCertPart;
const uint8 *pcRawOID;
uint32 uASNOID;
int nInstance;
}X509PartRequest;

成员：

nCertWebOpt
WEBOPT_X509_ROOT_CERTS、WEBOPT_X509_BRANCH_CERTS ... 之一
nCertIndex
要从中获取部分的证书
uCertPart
要从中获取部分的字段 下列之一：
  • X509CHAIN_FIELD_ISSUER
  • X509CHAIN_FIELD_SUBJECT
  • X509CHAIN_FIELD_EXTENSIONS
pcRawOID
指向主题、发布者或扩展部分的原始 OID。 必须有效或为 NULL。
uASNOID
以上常量，充当 OID 备选。
pcRawOID
必须为 NULL 才可使用它。
nInstance
初始值为 0。 （请注意，响应中包含实例总数）。

备注：

该结构大约 20 字节，因此可以在堆栈上实现。 可以使用它来指定获取证书部分所需的全部四个项目：

  • webopt id、
  • webopt/证书索引、
  • 证书中的字段以及
  • 字段中的部分 OID。

它用于获取具有不同名称的部分或 X509 v3 扩展。

有关用于指定字段部分 OID 的备用方案的信息，请参阅 AEEASN1OIDS。 此处的 ASNOID 是一组整数，对应于常用 OID 的 OID。 这比使用完全 DER/BER 编码的 OID 要方便许多。

另请参阅：

IX509CHAIN_GetFieldPart()

X509CertPart

返回数据结构列表

X509RSAKey

说明：

RSA 密钥的简单格式。

定义：

typedef struct X509RSAKey
{
const uint8 *puModulus;
uint16 uModulusLen;
const uint8 *puExponent;
uint16 uExponentLen;
}X509RSAKey;

成员：

puModulus | 指向模数字节
uModulusLen | 模数长度（以字节为单位）
puExponen | 指向指数字节的指针
uExponentLen | 指数长度（以字节为单位）

备注：

无

另请参阅：

IRSA 接口

IX509CHAIN_GetRSAKey()

返回数据结构列表

X509TrustOverride

说明：

该结构用于指定跳过特定信任检查

定义：

typedef struct
{
uint32 uCertID;
uint32 uOverrideBits;
}X509TrustOverride;

成员：

uCertID | 源于 X509BasicCert 数据结构。 如果 uCertID 全为零，则对链中的全部证书应用覆盖。 请注意这比较危险，尽管有些情况下是必需的。 使用无 SSL 的证书时，为了验证数字签名，需要验证主机名和检查日期。 关闭这些校验的方法是覆盖链中所有证书的这两个校验。
uOverrideBits | X509CHAIN_ 中的位映射，指示要覆盖的信任故障。

备注：

该数据结构的实例代表特定证书的一组信任覆盖。 通过添加以此结构为值、
以 WEBOPT_X509_OVERRIDE 为 ID 的选项可以使用它。该选项可添加到 IX509Chain 中或传递到 IX509CHAIN_Verify() 的参数中。

在短期或长期存储信任覆盖时，信任覆盖记录非常有用。 因为这种二进制格式不会随 Brew 版本变化而更改。

相同的宏/常量可用于指示信任错误或覆盖。 下面说明如何将这些位用作信任覆盖。 通常这些位会禁用信任检查的某些部分。

X509CHAIN_OVERRIDE_ALL 覆盖所有信任处理。 这很危险。

X509CHAIN_CERT_TRUST 在链操作期间将此证书作为根来信任。

X509CHAIN_LONG_CHAIN 不用作覆盖。 使用

WEBOPT_X509_MAX_CHAIN 代替

X509CHAIN_CERT_EXIPRED 不检查证书上的日期（但仍尝试解析日期）

X509CHAIN_BAD_DATE 关闭检查证书日期的所有尝试

X509CHAIN_HOST_MISMATCH 不尝试比较名称

X509CHAIN_NO_TARGET_HOST 与 X509CHAIN_HOST_MISMATCH 相同。
不尝试检查主机名

X509CHAIN_NO_HOST_IN_CERT 与 X509CHAIN_HOST_MISMATCH 相同。
不尝试检查主机名。

X509CHAIN_BAD_SIGNATURE 不尝试验证此证书上的签名，无重大秘密。

X509CHAIN_CERT_HASH_UNKNOWN 与 X509CHAIN_SEVER_CERT_SIG_BAD 相同

X509CHAIN_CERT_HASH_UNSUPP 与 X509CHAIN_SEVER_CERT_SIG_BAD 相同

X509CHAIN_SIGNER_KEY_BAD 停止对该证书所签发*的证书进行签名验证

X509CHAIN_CRITICAL_EXTENSION 将尝试检查已知扩展，但不加记录地忽略未知扩展。

X509CHAIN_BASIC_CONST 不检查基本约束

X509CHAIN_EXT_KEY_USE 忽略扩展密钥使用扩展（如果不是关键扩展）

X509CHAIN_CRIT_EXT_KEY_USE 完全忽略扩展密钥使用

X509CHAIN_KEY_USE 禁用所有密钥使用处理

另请参阅：

IX509CHAIN_Verify()

返回数据结构列表

X509TrustResult

说明：

用于提供评估证书链的结果

定义：

typedef struct X509TrustResult
{
int nResult;
int nChainLen;
uint32 auChainErrors[X509CHAIN_MAX_CHAIN];
uint32 uErrorSummary;
}X509TrustResult;

成员：

nResult
报告常规错误，例如内存不足或缺少叶节点证书，这些将导致不执行任何链验证。
nChainLen
指示链中的证书数量，进而指示在 auChainErrors 中检查错误的位置。 请注意，链可能不完整或无法向上链至根证书。
auChainErrors
如果 nResult 为 SUCCESS（成功），则结果包含于 auChainErrors 中。 它通过位字段说明链中各个级别的错误。 这些位为 X509CHAIN_*（如信任错误中所述）。 第
0 个整数为服务器证书，向上为根证书。
uErrorSummary
整个链中所有信任错误位的 OR 运算。 如果此值为零，则信任全部 OK（通过）。 该值在向用户报告一组比较简单的错误时也非常有用。

备注：

此结构大约 40 字节。 它由 IX509CHAIN_Verify 填写，以报告验证操作的结果。 除无法解析和丢失叶节点证书或服务器证书等错误以外，

其它任何相关错误均视为信任错误。 信任错误可以覆盖。

以下列出了各种信任错误：

X509CHAIN_TRUST_OK 在我们信任的 SSL 中未设置标记

X509CHAIN_CERT_TRUST 无法找到向上链接的证书，并无法到达根

X509CHAIN_LONG_CHAIN 达到最大链长度（硬限制或在选项中限制）；达到基本约束扩展中的路径长度时也可能返回。

X509CHAIN_CERT_EXIPRED 证书到期或无效

X509CHAIN_BAD_DATE 不能从证书中获取有效的开始或结束日期

X509CHAIN_HOST_MISMATCH 从证书中获得主机名，但与设置的主机不匹配

X509CHAIN_NO_TARGET_HOST 未指定主机的目标主机名。 未设置 WEBOPT_X509_HOST。

X509CHAIN_NO_HOST_IN_CERT 叶节点证书中不存在主机名

X509CHAIN_BAD_SIGNATURE 表示证书已损坏或篡改

X509CHAIN_CERT_HASH_UNKNOWN 不能判断证书上的签名所使用的散列

X509CHAIN_CERT_HASH_UNSUPP 已判断出散列，但是不支持该散列

X509CHAIN_SIGNER_KEY_BAD 签署者证书中的密钥在语法上无效

X509CHAIN_CRITICAL_EXTENSION 一些关键扩展未知

X509CHAIN_BASIC_CONST 违背证书的基本约束扩展

X509CHAIN_EXT_KEY_USE 指示链中的叶节点证书具有扩展密钥使用扩展，
且该扩展不包含

WEBOPT_X509_EXT_KEY_USE 选项中指定的全部预期用途。 或者，无论是否设置此选项，当作为扩展密钥的任何非叶节点证书使用标记为关键的扩展时，都会发生该错误。

X509CHAIN_CRIT_EXT_KEY_USE 同上，但扩展密钥使用已标记为关键

X509CHAIN_KEY_USE 具有密钥使用扩展的证书，该扩展已标记为关键扩展，
且不包含全部预期用途。 对于叶节点证书，预期用途来自 webopt

WEBOPT_X509_KEY_USE。 对于根和中间证书，用途必须为 ASNOID_KEYUSE_CERTSIGN（如果扩展为关键扩展）

另请参阅：

IX509CHAIN_Verify

返回数据结构列表


AEE 错误代码

本节列举返回的错误、错误的相关代码以及错误说明。


错误列表

错误代码分组如下：

基本错误代码

文件错误代码

网络错误代码

网络子系统错误

DNS (GetHostByName) 错误

数据库和地址簿错误

地址簿错误代码

Web 错误

VOCODER 错误

BluetoothTM 错误

多媒体错误

PosDet 错误


基本错误代码

错误 | 代码 | 说明
SUCCESS | 0 | 未出错。
AEE_SUCCESS | 0 | 操作成功
EFAILED | 1 | 常规失败。
ENOMEMORY | 2 | 内存不足。
ECLASSNOTSUPPORT | 3 | 不支持指定的类。
EVERSIONNOTSUPPORT | 4 | 不支持版本。
EALREADYLOADED | 5 | 已加载对象。
EUNABLETOLOAD | 6 | 无法加载对象/小程序。
EUNABLETOUNLOAD | 7 | 无法卸载对象/小程序。
EALARMPENDING | 8 | 警报挂起。
EINVALIDTIME | 9 | 时间无效。
EBADCLASS | 10 | 类对象为 NULL。
EBADMETRIC | 11 | 指定量度无效。
EEXPIRED | 12 | 应用程序/组件到期。
EBADSTATE | 13 | 状态无效。
EBADPARM | 14 | 参数无效。
ESCHEMENOTSUPPORTED | 15 | URL 资源类型无效。
EBADITEM | 16 | 项目无效。
EINVALIDFORMAT | 17 | 格式无效。
EINCOMPLETEITEM | 18 | 项目不完整。
ENOPERSISTMEMORY | 19 | 闪存不足。
EUNSUPPORTED | 20 | 不支持 API。
EPRIVLEVEL | 21 | 安全违规。
ERESOURCENOTFOUND | 22 |
EREENTERED | 23 |
EBADTASK | 24 |
EALLOCATED | 25 | 释放应用程序/模块时保持内存分配。
EALREADY | 26 | 操作已在进行中。
EADSAUTHBAD | 27 | ADS 相互验证失败。
ENEEDSERVICEPROG | 28 | 需要服务程序。
EMEMPTR | 29 | 内存指针出错。
EHEAP | 30 | 堆错误
EIDLE | 31 | 上下文（系统，接口等）空闲。
EITEMBUSY | 32 | 上下文（系统，接口等）繁忙。

返回错误列表


文件错误代码

文件错误代码等于基本 FILE_ERROR(0x100) 加上表中的代码。

错误 | 代码 | 说明
EFILEEXISTS | (0) | 文件存在。
EFILENOEXISTS | (+1) | 文件不存在。
EDIRNOTEMPTY | (+2) | 目录非空。
EBADFILENAME | (+3) | 文件名错误。
EBADSEEKPOS | (+4) | 定位位置错误。
EFILEEOF | (+5) | 文件结束。
EFSFULL | (+6) | 文件系统已满。
EFILEOPEN | (+7) | 文件已打开。

返回错误列表


网络错误代码

网络错误代码等于基本 NET_ERROR_BASE(0x200) 加上表中代码。

错误 | 代码 | 说明
AEE_NET_SUCCESS | (0) | 操作成功。
AEE_NET_ERROR | (-1) | 操作失败。
AEE_NET_WOULDBLOCK | (-2) |
AEE_STREAM_WOULDBLOCK |  | 参见 AEE_NET_WOULDBLOCK。
AEE_NET_EEOF | (+1) | 文件结束。
AEE_NET_EBADF | (+2) | 套接字描述符无效。
AEE_NET_EFAULT | (+3) | 缓冲区或参数无效。
AEE_NET_EWOULDBLOCK | (+4) | 操作将中断。
AEE_NET_EAFNOSUPPORT | (+5) | 不支持地址族。
AEE_NET_EPROTOTYPE | (+6) | 套接字协议类型错误。
AEE_NET_ESOCKNOSUPPORT | (+7) | 不支持套接字参数。
AEE_NET_EPROTONOSUPPORT | (+8) | 不支持协议。
AEE_NET_EMFILE | (+9) | 没有更多可打开的套接字。
AEE_NET_EOPNOTSUPP | (+10) | 不支持操作。
AEE_NET_EADDRINUSE | (+11) | 地址已在使用中。
AEE_NET_EADDRREQ | (+12) | 要求目标地址。
AEE_NET_EINPROGRESS | (+13) | 正在建立连接。
AEE_NET_EISCONN | (+14) | 已经建立连接。
AEE_NET_EIPADDRCHANGED | (+15) | IP 地址更改，导致 TCP 重置。
AEE_NET_ENOTCONN | (+16) | 未连接套接字。
AEE_NET_ECONNREFUSED | (+17) | 拒绝连接尝试。
AEE_NET_ETIMEDOUT | (+18) | 连接尝试超时。
AEE_NET_ECONNRESET | (+19) | 连接重置。
AEE_NET_ECONNABORTED | (+20) | 连接中断。
AEE_NET_EPIPE | (+21) | 管道损坏。
AEE_NET_ENETDOWN | (+22) | 网络子系统不可用。
AEE_NET_EMAPP | (+23) | 没有可用的应用程序。
AEE_NET_EBADAPP | (+24) | 应用程序 ID 无效。
AEE_NET_SOCKEXIST | (+25) | 已存在套接字。
AEE_NET_EINVAL | (+26) | 操作无效。

返回错误列表


网络子系统错误

网络错误代码等于基本 NET_ERROR_BASE(0x200) 加上表中代码。

错误 | 代码 | 说明
AEE_NET_ENETISCONN | (+40) | 子系统已建立并可用。
AEE_NET_ENETINPROGRESS | (+41) | 正在建立子系统。
AEE_NET_ENETNONET | (+42) | 网络子系统不可用。
AEE_NET_ENETCLOSEINPROGRESS | (+43) | 正在关闭 PPP。
AEE_NET_ENETEXIST | (+44) | 现有的网络子系统资源。
AEE_NET_GENERAL_FAILURE | (+65) | 常规失败。

返回错误列表


DNS (GetHostByName) 错误

网络错误代码等于基本 NET_ERROR_BASE(0x200) 加上表中代码。

错误 | 代码 | 说明
AEE_NET_BADDOMAIN | (+50) | 域名称未正确格式化。
AEE_NET_UNKDOMAIN | (+51) | 未知域/无地址记录。

返回错误列表


数据库和地址簿错误

数据库错误代码等于基本 DB_ERROR_BASE(0x300) 加上表中代码。

错误 | 代码 | 说明
AEE_DB_EBADREC | (0) |
AEE_DB_EBADSTATE | (+1) |
AEE_DB_ENULLREC | (+2) |
AEE_DB_ENULLFIELD | (+3) |
AEE_DB_EBADFIELDNUM | (+4) |

返回错误列表


地址簿错误代码

数据库错误代码等于基本 DB_ERROR_BASE(0x300) 加上表中代码。

错误 | 代码 | 说明
AEE_ADDR_INVALID_FIELD_ID | (+10) | 字段 ID 无效或不支持。
AEE_ADDR_INVALID_FIELD_VALUE | (+11) | 字段数据值无效。
AEE_ADDR_REC_NOT_FOUND | (+12) | 找不到记录。
AEE_ADDR_INVALID_REC | (+13) | 记录无效。
AEE_ADDRBOOK_EBADSTATE | (+14) | 地址簿处于错误状态。
AEE_ADDRBOOK_NOCATSUPPORT | (+15) | 不支持类别。
AEE_ADDR_CAT_NOT_SUPPORTED | (+16) | 不支持该类别。
AEE_ADDRBOOK_ERR | (-1) | 操作失败。

返回错误列表


Web 错误

Web 错误代码等于基本 WEB_ERROR_BASE(0x500) 加上表中代码。

错误 | 代码 | 说明
WEB_ERROR_PROTOCOL | (+1) | 协议错误。 因协议无效而无法处理的“扩展信息请求”时，将返回此值或相关错误消息。
WEB_ERROR_BADURL | (+2) | URL 残缺。
WEB_ERROR_BADHOSTNAME | (+3) | URL 中的主机名残缺。
WEB_ERROR_BADPORT | (+4) | URL 中的端口残缺。
WEB_ERROR_UNSUPSCHEME | (+5) | 不支持资源类型，找不到处理程序。
WEB_ERROR_DNSCONFIG | (+6) | 未配置 DNS 服务器。
WEB_ERROR_DNSTIMEOUT | (+7) | 服务器没有响应。
WEB_ERROR_ADDRUNKNOWN | (+8) | DNS 服务器响应地址未知。
WEB_ERROR_CONNECT | (+9) | 某种连接错误。
WEB_ERROR_SEND | (+10) | 写入套接字时出错。
WEB_ERROR_RECV | (+11) | 读取套接字时出错。
WEB_ERROR_BADRESPONSE | (+12) | 头信息残缺。
WEB_ERROR_BODYLENGTH | (+13) | 已指定请求正文，但未提供内容长度，或提供了错误的内容长度
WEB_ERROR_PROXYSPEC | (+14) | 代理说明无效。
WEB_ERROR_SSL | (+15) | SSL 特定错误，请求响应扩展信息

返回错误列表


VOCODER 错误

VOCODER 错误代码等于基本 VOCODER_ERROR_BASE (0x700) 加上表中的代码。

错误 | 代码 | 说明
AEE_VOC_STOP_PENDING | + 1 |
AEE_VOC_ENOT_AVAIL | + 2 |
AEE_VOC_EIN_USE | + 3 |
AEE_VOC_ENOT_IN_USE | + 4 |
AEE_VOC_ENOT_CONFIGED | + 5 |
AEE_VOC_ERATE_OUT_OF_RANGE | + 6 |
AEE_VOC_EDURATION_TOO_LONG | + 7 |
AEE_VOC_EDURATION_TOO_SHORT | + 8 |
AEE_VOC_EBUFFER_IN_USE | + 9 |
AEE_VOC_EBUFFER_NOT_EMPTY | + 10 |
AEE_VOC_EBUFFER_EMPTY | + 11 |
AEE_VOC_EBUFFER_FULL | + 12 |
AEE_VOC_EINCOMPATIBLE_CONFIG | + 13 |
AEE_VOC_EINCOMPATIBLE_OP | + 14 |

返回错误列表


BluetoothTM 错误

BlueTooth 错误代码等于基本 BLUETOOTH_ERROR_BASE (0x800) 加上表中的代码。

错误 | 代码 | 说明
AEE_BT_SUCCESS |  | 操作成功
AEE_BT_ERROR |  | 操作失败
AEE_BT_WOULDBLOCK |  | 操作中断
AEE_BT_EBADF |  | 描述符无效
AEE_BT_EFAULT |  | 缓冲区或参数无效
AEE_BT_EINPROGRESS |  | 正在建立连接
AEE_BTSDP_EINPROGRESS |  | 正在进行发现
AEE_BT_EINVAL |  | 操作无效
AEE_BT_ECONNABORTED |  | 连接中断

返回错误列表


多媒体错误

多媒体错误代码等于基本 MM_ERROR_BASE (0x900) 加上表中的代码。

错误 | 代码 | 说明
MM_ERROR | -1 | 命令失败
MM_PENDING | -2 | 接受的命令已排入队列。 通过注册的回调返回结果。
MM_EBADMEDIADATA | + 1 | 媒体数据错误
MM_ENOMEDIAMEMORY | + 2 | 未存储 IMedia 对象
MM_EMIDIOUTNOTOPEN | + 3 | 未打开 MIDI 输出设备
MM_EMOREDATAREQ | + 4 | 需要更多数据才能执行指定的操作
MM_EPEEK | + 5 | 发生 IPeek 错误
MM_ENOTENOUGHTDATA | + 6 | 因数据不足而中断操作

返回错误列表


PosDet 错误

PosDet 错误代码等于基本 AEEGPS_ERR_BASE (0x00100000) 加上表中的代码。

错误 | 代码 | 说明
AEEGPS_ERR_NO_ERR | 0 | 成功
AEEGPS_ERR_GENERAL_FAILURE | + 1 | 常规失败
AEEGPS_ERR_TIMEOUT | + 2 | 超时
AEEGPS_ERR_ACCURACY_UNAVAIL | + 3 | 精确度不可用
AEEGPS_ERR_INFO_UNAVAIL | + 4 | 信息不可用

返回错误列表


ISSL 错误

ISSL 错误代码等于基本 ISSL_ERROR_BASE (0x1200) 加上表中的代码。

错误 | 代码 | 说明
SSL_RESULT_SECURED | 0 | 连接受到保护
SSL_RESULT_ALGS_ERR | 1 | 无通用算法，但它可能指示发送 HANDSHAKE 警告时设置的某个其它错误，该错误不一定是 SSL3 中的算法错误。 它位于 TLSv1 中
SSL_RESULT_TRUST_ERR | 2 | 存在信任错误。 参见错误 TrustResult
SSL_RESULT_CERT_ERR | 3 | 证书链中存在不可覆盖的问题。 参见 TrustResult
SSL_RESULT_PROTO_ERR | 4 | 协议交互存在基础错误。
SSL_RESULT_CLIENT_AUTH_ERR | 5 | 服务器要求客户端验证
SSL_RESULT_CLOSED | 6 | 会话已安全关闭
SSL_RESULT_HANDSHAKE | 7 | 握手出错，例如 mac 错误
SSL_RESULT_NOMEM | 8 | 内存不足， 无法继续。
SSL_RESULT_UNINITIALIZED | 9 | 您忘记了设置 ISSL 中的某些项，如服务器套接字
SSL_RESULT_ERR | 10 | 您正在执行严重错误的操作，好在我们发现了错误，而未切断您的电话。
SSL_RESULT_BAD_SOCKET | 11 | 该 Brew 编译不支持 SSL 所需的套接字处理。 该错误最终被将消除
SSL_RESULT_CONFIG | 12 | 内部配置错误。 获知此错误时，很可能已发生严重问题
SSL_RESULT_VERS_UNSUP | 13 | 客户端不支持任何请求的 SSL 协议版本
SSL_RESULT_CSUITE_UNSUP | 14 | 客户端不支持任何请求的密码组
SSL_RESULT_SERV_VERS | 15 | 服务器不支持协议版本或版本
SSL_RESULT_TRUST_CHECK | 16 | 客户端暂停未完成的信任检查
SSL_RESULT_SOCKET_ERROR | 17 | 套接字错误。 使用 ISOCKET_GetLastError 可以获取套接字错误代码


按键代码

下表列出了 BREW 支持的按键代码。

按键代码由 EVT_KEY、EVT_KEY_PRESS、EVT_KEY_RELEASE、EVT_KEY_HELD 和 EVT_UPDATECHAR 事件接收。


按键代码

按键代码 | 说明
AVK_UNDEFINED | 无效的按键代码
AVK_0 | 0 键
AVK_1 | 1 键
AVK_2 | 2 键
AVK_3 | 3 键
AVK_4 | 4 键
AVK_5 | 5 键
AVK_6 | 6 键
AVK_7 | 7 键
AVK_8 | 8 键
AVK_9 | 9 键
AVK_STAR | * 键
AVK_POUND | # 键
AVK_POWER | 开机键
AVK_SEND | 发送键
AVK_END | 结束键
AVK_CLR | 清除键
AVK_UP | 向上键
AVK_DOWN | 向下键
AVK_LEFT | 向左键
AVK_RIGHT | 向右键
AVK_SELECT | 选择键
AVK_SOFT1 | 软键 1
AVK_SOFT2 | 软键 2
AVK_SOFT3 | 软键 3
AVK_SOFT4 | 软键 4
AVK_FUNCTION1 | 功能键 1
AVK_FUNCTION2 | 功能键 2
AVK_FUNCTION3 | 功能键 3
AVK_FUNCTION | 功能键
AVK_MENU | 菜单键
AVK_INFO | 信息键
AVK_SHIFT | Shift 键
AVK_MESSAGE | 消息键
AVK_MUTE | 静音键
AVK_STORE | 存储键
AVK_RECALL | 撤消键
AVK_PUNC1 | 标点键 1
AVK_PUNC2 | 标点键 2
AVK_VOLUME_UP | 增加音量键
AVK_VOLUME_DOWN | 降低音量键
AVK_WEB_ACCESS | Web 接入键
AVK_VOICE_MEMO | 语音备忘键
AVK_SPEAKER | 扬声器键
AVK_TAP | TAP 键
AVK_PTT | 按讲键
AVK_LSHIFT | 左 Shift 键
AVK_RSHIFT | 右 Shift 键
AVK_LCTRL | 左 Ctrl 键
AVK_RCTRL | 右 Ctrl 键
AVK_LALT | 左 Alt/菜单键
AVK_RALT | 右 Alt/菜单键
AVK_CAPLK | Caps Lock 键
AVK_SCRLK | Scroll Lock 键
AVK_NUMLK | Num Lock 键
AVK_LNGHANGUL | Hangul 语言键
AVK_LNGJUNJA | Junja 语言键
AVK_LNGFIN | 语言结束键
AVK_LNGHANJA | Hanja 语言键
AVK_PRSCRN | Print Screen 键
AVK_BREAK | Break 键
AVK_TXINSERT | Insert 键
AVK_TXDELETE | Delete 键
AVK_TXHOME | Home 键
AVK_TXEND | End 键，不是 AVK_END
AVK_TXPGUP | Page Up 键
AVK_TXPGDOWN | Page Down 键
AVK_LAST | 未用。


修改键的位

键位 | 按键
KB_LSHIFT | 左 Shift
KB_LSHIFT | 左 Shift
KB_RSHIFT | 右 Shift
KB_LCTRL | 左 Ctrl
KB_RCTRL | 右 Ctrl
KB_LALT | 左 Alt 或菜单键
KB_RALT | 右 Alt 或菜单键
KB_CAPSLOCK | Caps Lock
KB_SCROLLLK | Scroll Lock
KB_NUMLOCK | Num Lock

注意： IS_KEY_DOWN (uint32 bitFlags,uint32 kbKey) 将返回：TRUE，如果按键按下/弹起；FALSE， 如果按键没有按下/弹起。bitFlags 参数通常是 KEY 和 CHAR 事件中传递的 dwParam 参数。kbKey 是“修改键的位”表中的位定义。

修改键示例

如果用户按下 Ctrl+C，并且电话支持左 Ctrl 和 C 键，则将发生以下事件系列。

  • EVT_KEY_PRESS: wParam 为 AVK_LCTRL。dwParam 设置 KB_LCTRL 位。
  • EVT_KEY: wParam 为 AVK_LCTRL。dwParam 设置 KB_LCTRL 位。
  • EVT_KEY_PRESS: wParam 为 (AECHAR)'C'。dwParam 设置 KB_LCTRL 位。
  • EVT_KEY: wParam 为 (AECHAR)'C'。dwParam 设置 KB_LCTRL 位。
  • EVT_CHAR: wParam 为 (AECHAR)'c'。dwParam 设置 KB_LCTRL 位。
    请注意，使用小写的 c 是因为 Caps Lock 和 Shift 键都未处于按下状态。
  • EVT_KEY_RELEASE: wParam 为 (AECHAR)'C'。dwParam 仍设置 KB_LCTRL 位。
  • EVT_KEY_RELEASE: wParam 为 AVK_LCTRL。dwParam 现取消设置 KB_LCTRL 位。
提示： 如果使用启用了字符仿真的 SDK，并且电话不支持左 Ctrl 或 C 键，则您将仅接收一个事件：
  • EVT_CHAR: wParam 为 (AECHAR)'c'。dwParam 设置 KB_LCTRL 位。


AEECLSID 列表

QVERSION 定义为 0x01000000，其中最高有效 8 位表示版本。

CLSIDS (ClassIDs)

AEECLSID_PRIV | QVERSION
AEECLSID_CORE | QVERSION + 0x1000
AEECLSID_ENH | QVERSION + 0x2000
AEECLSID_CONTROL | QVERSION + 0x3000
AEECLSID_VIEW | QVERSION + 0x4000
AEECLSID_PROTO | QVERSION + 0x5000
AEECLSID_MULTIMEDIA | QVERSION + 0x5500
AEECLSID_OEM | QVERSION + 0x6000
AEECLSID_OEM_APP | QVERSION + 0x7000
AEECLSID_SAMPLE_APP | QVERSION + 0x8000
AEECLSID_USAGE_APP | QVERSION + 0x9000
AEECLSID_BREWFONTS | QVERSION + 0xA000
AEECLSID_APP | 0x01010100
AEECLSID_APPLET | AEECLSID_APP
AEECLSID_SCREEN_SAVER | AEECLSID_APP + 1
AEECLSID_EXTENSION | 0x01800000
AEECLSID_RANGE | 0x00000fff

保护类 -不能更新

AEECLSID_DOWNLOAD | AEECLSID_PRIV
AEECLSID_QUERYINTERFACE | AEECLSID_PRIV+1
AEECLSID_COREAPP | AEECLSID_PRIV+2
AEECLSID_ADSQUERY | AEECLSID_PRIV+3

内核类

AEECLSID_SHELL | AEECLSID_CORE
AEECLSID_DISPLAY | AEECLSID_CORE+1
AEECLSID_HEAP | AEECLSID_CORE+2
AEECLSID_FILEMGR | AEECLSID_CORE+3
AEECLSID_NET_10 | AEECLSID_CORE+5
AEECLSID_TAPI | AEECLSID_CORE+7
AEECLSID_DBMGR | AEECLSID_CORE+8
AEECLSID_DIALOG | AEECLSID_CORE+9
AEECLSID_STATIC_10 | AEECLSID_CORE+10
AEECLSID_SOUND | AEECLSID_CORE+11
AEECLSID_MEMASTREAM | AEECLSID_CORE+12
AEECLSID_PHONE | AEECLSID_CORE+14
AEECLSID_LICENSE | AEECLSID_CORE+15
AEECLSID_CERTCACHE | AEECLSID_CORE+16
AEECLSID_SOURCEUTIL | AEECLSID_CORE+17
AEECLSID_SOURCE | AEECLSID_CORE+18
AEECLSID_GETLINE | AEECLSID_CORE+19
AEECLSID_UNZIPSTREAM | AEECLSID_CORE+20
AEECLSID_MD5 | AEECLSID_CORE+21
AEECLSID_RSCPOOL | AEECLSID_CORE+22
AEECLSID_THREAD | AEECLSID_CORE+23
AEECLSID_PORT | AEECLSID_CORE+24
AEECLSID_ARC4 | AEECLSID_CORE+25
AEECLSID_RSA | AEECLSID_CORE+26
AEECLSID_POSDET_11 | AEECLSID_CORE+27
AEECLSID_PEEK | AEECLSID_CORE+28
AEECLSID_PROVISION | AEECLSID_CORE+29
AEECLSID_RESTORE | AEECLSID_CORE+30
AEECLSID_PROVISIONITEM | AEECLSID_CORE+31
AEECLSID_CLIPBOARD | AEECLSID_CORE+32
AEECLSID_BITMAP | AEECLSID_CORE+33
AEECLSID_FONT | AEECLSID_CORE+34
AEECLSID_AEEDIB | AEECLSID_CORE+35
AEECLSID_DEVPORTMGR | AEECLSID_CORE+36
AEECLSID_SERIALPORTMGR | AEECLSID_CORE+37
AEECLSID_SERIALCONFIG | AEECLSID_CORE+38
AEECLSID_CONFIG | AEECLSID_CORE+39
AEECLSID_SPRITE | AEECLSID_CORE+40
AEECLSID_TRANSFORM | AEECLSID_CORE+41
AEECLSID_POSDET | AEECLSID_CORE+42
AEECLSID_DISPLAYCLONE | AEECLSID_CORE+43
AEECLSID_DIB | AEECLSID_CORE+44
AEECLSID_SOCKET | AEECLSID_CORE+45
AEECLSID_NET | AEECLSID_CORE+46
AEECLSID_ASTREAM | AEECLSID_CORE+47
AEECLSID_BASE | AEECLSID_CORE+48
AEECLSID_CORE_LAST | AEECLSID_CORE+49

增强类

AEECLSID_SOUNDPLAYER | AEECLSID_ENH
AEECLSID_GRAPHICS | AEECLSID_ENH+1
AEECLSID_VOICE | AEECLSID_ENH+2
AEECLSID_RINGERMGR | AEECLSID_ENH+3
AEECLSID_ADDRBOOK | AEECLSID_ENH+4
AEECLSID_SAXREADER | AEECLSID_ENH+5
AEECLSID_SAXCONTENTHANDLER | AEECLSID_ENH+6
AEECLSID_SAXATTRIBUTES | AEECLSID_ENH+7
AEECLSID_SAXLOCATOR | AEECLSID_ENH+8
AEECLSID_BTSIOPORT | AEECLSID_ENH+9
AEECLSID_VOCODER | AEECLSID_ENH+10
AEECLSID_BTSDP | AEECLSID_ENH+11

UI 控件

AEECLSID_MENUCTL_10 | AEECLSID_CONTROL
AEECLSID_SOFTKEYCTL_10 | AEECLSID_CONTROL+1
AEECLSID_LISTCTL_10 | AEECLSID_CONTROL+2
AEECLSID_ICONVIEWCTL_10 | AEECLSID_CONTROL+3
AEECLSID_DATEPICKCTL | AEECLSID_CONTROL+4
AEECLSID_DATECTL | AEECLSID_CONTROL+5
AEECLSID_STOPWATCHCTL | AEECLSID_CONTROL+6
AEECLSID_CLOCKCTL | AEECLSID_CONTROL+7
AEECLSID_COUNTDOWNCTL | AEECLSID_CONTROL+8
AEECLSID_TEXTCTL | AEECLSID_CONTROL+9
AEECLSID_ACLOCKCTL | AEECLSID_CONTROL+10
AEECLSID_IMAGECTL | AEECLSID_CONTROL+11

1.NNN 版本...

AEECLSID_NET_11 | AEECLSID_NET_10 + 0x100
AEECLSID_STATIC | AEECLSID_STATIC_10 + 0x100
AEECLSID_MENUCTL | AEECLSID_MENUCTL_10 + 0x100
AEECLSID_SOFTKEYCTL | AEECLSID_SOFTKEYCTL_10 + 0x100
AEECLSID_LISTCTL | AEECLSID_LISTCTL_10 + 0x100
AEECLSID_ICONVIEWCTL | AEECLSID_ICONVIEWCTL_10 + 0x100

浏览器

AEECLSID_WINBMP | AEECLSID_VIEW+1
AEECLSID_NATIVEBMP | AEECLSID_VIEW+2
AEECLSID_GIF | AEECLSID_VIEW+3
AEECLSID_PNG | AEECLSID_VIEW+4
AEECLSID_JPEG | AEECLSID_VIEW+5
AEECLSID_BCI | AEECLSID_VIEW+6
AEECLSID_HTML | AEECLSID_VIEW+7

编码

AEECLSID_ENCODING | AEECLSID_VIEW+ 0x100
AEECLSID_ENCODING_UTF16 | AEECLSID_ENCODING + 0x01
AEECLSID_ENCODING_UTF8 | AEECLSID_ENCODING + 0x02
AEECLSID_ENCODING_USASCII | AEECLSID_ENCODING_UTF8
AEECLSID_ENCODING_ISOLATIN1 | AEECLSID_ENCODING + 0x03

编码转换

AEECLSID_ENCODE | AEECLSID_ENCODING + 0x200
AEECLSID_ENCODE_UTF16TOUTF8 | AEECLSID_ENCODE + 0x01
AEECLSID_ENCODE_ISOLATIN1TOUTF8 | AEECLSID_ENCODE + 0x02

协议句柄

AEECLSID_WEB | AEECLSID_PROTO
AEECLSID_WEBUTIL | AEECLSID_PROTO+1
AEECLSID_WEBRESP | AEECLSID_PROTO+2
AEECLSID_WEBREQ | AEECLSID_PROTO+3
AEECLSID_WEBOPTS | AEECLSID_PROTO+4
AEECLSID_WEBENG | AEECLSID_PROTO+5
AEECLSID_BROWSER | 0x01007100

基于 IMedia 类的多媒体格式句柄

AEECLSID_MEDIA | AEECLSID_MULTIMEDIA
AEECLSID_MEDIAMIDI | AEECLSID_MULTIMEDIA + 1
AEECLSID_MEDIAMP3 | AEECLSID_MULTIMEDIA + 2
AEECLSID_MEDIAQCP | AEECLSID_MULTIMEDIA + 3
AEECLSID_MEDIAPMD | AEECLSID_MULTIMEDIA + 4
AEECLSID_MEDIAMIDIOUTMSG | AEECLSID_MULTIMEDIA + 5
AEECLSID_MEDIAMIDIOUTQCP | AEECLSID_MULTIMEDIA + 6
AEECLSID_MEDIAMPEG4 | AEECLSID_MULTIMEDIA + 7
AEECLSID_MEDIAMMF | AEECLSID_MULTIMEDIA + 8

OEM 显示设备的类 ID

AEECLSID_DISPMAIN | AEECLSID_OEM + 1
AEECLSID_DISP2 | AEECLSID_OEM + 2
AEECLSID_DISP3 | AEECLSID_OEM + 3
AEECLSID_DISP4 | AEECLSID_OEM + 4

扩展类

AEECLSID_ENCODE_SHIFTJIS
AEECLSID_EXTENSION + 1

字体

AEECLSID_FONT_FIXED4X6 | AEECLSID_BREWFONTS + 1
AEECLSID_FONT_BASIC6 | AEECLSID_BREWFONTS + 2
AEECLSID_FONT_BASIC9 | AEECLSID_BREWFONTS + 3
AEECLSID_FONT_BASIC10 | AEECLSID_BREWFONTS + 4
AEECLSID_FONT_BASIC11 | AEECLSID_BREWFONTS + 5
AEECLSID_FONT_BASIC11B | AEECLSID_BREWFONTS + 6
AEECLSID_FONT_BASIC14 | AEECLSID_BREWFONTS + 7
AEECLSID_BITFONTFOUNDRY | AEECLSID_BREWFONTS + 0x100


AEEASN1OIDS

在获取一些证书部分时，为方便起见，将 ASN.1 空间分解至数个 ID。 简而言之： 从下面选择您需要的值，并将其传递到 X509Chain_GetFieldPart。

此处有我们所需的有限数量的 OID 子空间。 其中任意一个可能包含几个到几百个相关的 OID。

因此，我们划分一个 32 位整数，使得高 8 位代表子空间，低 24 位代表子空间中的值。

这种方法有效的原因是，OID 的最后一个字节没有采用其它字节所采用的奇怪的编码方式。
因此，我们可以向下模式匹配到子空间，然后只需在最后字节中使用 OR 运算来获取以下值（如果该操作有意义）。

由于这些空间中包含大量的可能全世界仅有少数几个人才关心的 OID，因此无需为所有 OID 定义常量。但如果您恰好是这些少数关注者之一，您仍可以通过 ASNOID_MATCH_SUBSPACE 宏来使用此代码。

ASNOID_UNDEFINED | 0x00 | 我们所未知的，祝你好运玩得开心！
ASNOID_SUBSPACES | 0xff000000 | 子空间掩码

ASNOID_MATCH_SUBSPACE(oid, subspace) ((oid & ASNOID_SUBSPACES) == subspace)
ASNOID_UNKNOWN 0xff000001
ASNOID_ANY 0xff000002

2.5.4 这是联合 ITU/ISO X.500 属性树，并包含以不同名称使用的内容

二进制 DER 前缀 \x06\0x03\x55\x04

ASNOID_X500 | 0x01000000 | ASNOID 的 X.500 子空间
ASNOID_X500_CN | 0x01000003 | 2.5.4.3 通用名称
ASNOID_X500_CO | 0x01000006 | 2.5.4.6 国家
ASNOID_X500_LO | 0x01000007 | 2.5.4.7 地区名称
ASNOID_X500_ST | 0x01000008 | 2.5.4.8 州或省名称
ASNOID_X500_O | 0x0100000A | 2.5.4.10 组织名称
ASNOID_X500_OU | 0x0100000B | 2.5.4.11 组织单位名称

1.2.840.113549.1.1 这是 PKCS1 空间。 PKCS 一部分，PKCS 属于 RSADSI 一部分，而 RSADSI 属于 ISO 成员体 US 一部分...

二进制 DER 前缀为 \x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01

ASNOID_PKCS1 | 0x02000000 | ASNOIDS 的 PKCS1 子空间
ASNOID_PKCS1_RSA | 0x02000001 | 1.2.840.113549.1.1.1 rsa 加密
ASNOID_PKCS1_RSA_MD2 | 0x02000002 | 1.2.840.113549.1.1.2 rsa MD2 加密
ASNOID_PKCS1_RSA_MD5 | 0x02000004 | 1.2.840.113549.1.1.4 RSA md5 加密
ASNOID_PKCS1_RSA_SHA1 | 0x02000005 | 1.2.840.113549.1.1.5 RSA sha1 加密

1.3.14.3.2 这是 secsig 子空间，它部分属于 OIW，部分属于 ISO 组织（如同此处已标识的许多保密算法）。 在现有基础上，可能值得添加更多定义...

二进制 DER 前缀为 \x06\x05\x2b\x0e\x03x02

ASNOID_SECSIG | 0x03000000 | ASNOIDS 的 secsig 子空间
ASNOID_SECSIG_SHA1 | 0x0300001A | 1.3.14.3.2.26 SHA-1 散列

2.5.29. 这是证书扩展的联合 ITU/ISO X.500 目录树区域

这里可能有更多值得为之定义常量的 OID

二进制 DER 前缀为 \x06\x03\x55\x1d

ASNOID_CERTEXT | 0x04000000 | ASNOIDS 的证书扩展子空间
ASNOID_CERTEXT_POLICIES | 0x04000003 | 2.5.29.3 证书政策
ASNOID_CERTEXT_SUBJKEY_ID | 0x0400000E | 2.5.29.14 用户密钥标识
ASNOID_CERTEXT_KEY_USE | 0x0400000F | 2.5.29.15 密钥用途
ASNOID_CERTEXT_SUBJALTNAME | 0x04000010 | 2.5.29.16 用户备用名
ASNOID_CERTEXT_ISSALTNAME | 0x04000011 | 2.5.29.17 签发者备用名
ASNOID_CERTEXT_B_CONSTRAIN | 0x04000013 | 2.5.29.19 基本约束
ASNOID_CERTEXT_CRLDIT | 0x0400001F | 2.5.29.31 CRL 分发点
ASNOID_CERTEXT_POLICIES2 | 0x04000020 | 2.5.29.32 证书政策
ASNOID_CERTEXT_AUTHKEY_ID | 0x04000023 | 2.5.29.35 认证密钥标识
ASNOID_CERTEXT_EXT_KEY_USE | 0x04000025 | 2.5.29.37 扩展密钥用途

2.16.840.1.113730.1 ISO/ITU 由国家 - 美国公司 Netscape 联合分配

Netscape 证书扩展

二进制 DER 前缀为 \x06\x09\x60\x86\x48\x01\x86\xf8\x42\x01

ASNOID_NETSCAPE_CERT_EXT | 0x05000000 | ASNOIDS 的 Netscape 子空间
ASNOID_NETSCAPE_CERT_EXT_TYPE | 0x05000001 | 2.16.840.1.113730.1.1 - Netscape 证书类型
ASNOID_NETSCAPE_CERT_EXT_GEN | 0x0500000D | 2.16.840.1.113730.1.13 - 由以下对象生成

2.16.840.1.113733.1 ISO/ITU 由国家 - 美国公司 Verisign 证书政策联合分配

二进制 DER 前缀为 \x06\x0B\x60\x86\x48\x01\x86\xf8\x45\x01\x07\x01

ASNOID_VERISIGN_POLICY | 0x06000000 | Verisign 证书政策
ASNOID_VERISIGN_POLICY_QUAL1 | 0x06000001 | Verisign 政策合格者
ASNOID_VERISIGN_POLICY_QUAL2 | 0x06000002 | Verisign 政策合格者

1.3.6.1.4.1.311.10.3 ISO 标识组织、US DoD、Internet 分配、私有、IANA 已注册企业、Microsoft

二进制 DER 前缀为 \x06\x0A\x2b\x06\x01\x04\x01\x82\x37\x01\x03

ASNOID_MICROSOFT | 0x07000000 | Microsoft 的子空间
ASNOID_MICROSOFT_SGC | 0x07000003 | 服务器门控加密技术

2.16.840.4.113730.1 ISO/ITU 由国家 - 美国公司 Netscape International Step up 联合分配。

二进制 DER 前缀为 \x06\x09\x60\x86\x48\x01\x86\xf8\x42\x04

ASNOID_NETSCAPE_STEP | 0x08000000 | ASNOIDS 的 Netscape 子空间
ASNOID_NETSCAPE_STEP_UP | 0x08000001 | 2.16.840.1.113730.4 - International step up

1.2.840.113549.1.9 这是 PKCS9 空间。 PKCS 一部分，PKCS 属于 RSADSI 一部分，而 RSADSI 属于 ISO 成员体 US 一部分...

二进制 DER 前缀为 \x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x09

ASNOID_PKCS9 | 0x09000000 | ASNOIDS 的 PKCS9 子空间
ASNOID_PKCS9_EMAIL | 0x09000001 | 1.2.840.113549.1.9.1 电子邮件地址

1.3.6.1.5.5.7.1 此 ISO 标识组织、US Dod、因特网分配、IANA 安全、机制、pkix、私有证书扩展

二进制 DER 前缀为 \x06\x08\x2B\x06\x01\x05\x05\x07\x01

ASNOID_PKIXPRIV | 0x0a000000 | ASNOIDS 的私有证书扩展 PKIX 子空间
ASNOID_PKIXPRIV_AUTHINFO | 0x0a000001 | 1.3.6.1.5.5.7.1.1 认证信息访问字段

2.16.840.1.113733.1 ISO/ITU 由国家 - 美国公司 Verisign 联合分配

二进制 DER 前缀为 \x06\x0a\x60\x86\x48\x01\x86\xf8\x45\x01\x06

ASNOID_VERISIGNPRIV | 0x0b000000 | Verisign 秘密分配
ASNOID_VERISIGNPRIV_BREWPERM | 0x0b000011 | Brew 数字 sig 许可

1.2.840.113549.2 这些是 PKCS1 空间中的摘要算法。 PKCS 一部分，PKCS 属于 RSADSI 一部分，而 RSADSI 属于 ISO 成员体 US 一部分...

二进制 DER 前缀为 \x06\x08\x2a\x86\x48\x86\xf7\x0d\x02

ASNOID_PKCS1DIGEST | 0x0c000000 |
ASNOID_PKCS1DIGEST_MD2 | 0x0c000002 | MD2 算法
ASNOID_PKCS1DIGEST_MD5 | 0x0c000005 | MD5 算法
ASNOID_PKCS1DIGEST_SHA1 | 0x0c000007 | SHA1 算法

1.3.6.1.5.5.7.3 此 ISO 标识组织、US Dod、因特网分配、IANA 安全、机制、pkix、扩展密钥用途。

二进制 DER 前缀为 \x06\x08\x2B\x06\x01\x05\x05\x07\x03

ASNOID_EXTKEYUSE | 0x0d000000 | ASNOIDS PKIX 子空间的扩展密钥用途
ASNOID_EXTKEYUSE_SRVRAUTH | 0x0d000001 | 1.3.6.1.5.5.7.3.1 TLS 服务器验证
ASNOID_EXTKEYUSE_CLNTAUTH | 0x0d000002 | 1.3.6.2.5.5.7.3.1 TLS 客户机验证
ASNOID_EXTKEYUSE_CODESIGN | 0x0d000003 | 1.3.6.1.5.5.7.3.3 代码签署
ASNOID_EXTKEYUSE_EMAIL | 0x0d000004 | 1.3.6.1.5.5.7.3.4 电子邮件保护
ASNOID_EXTKEYUSE_TIMESTMP | 0x0d000005 | 1.3.6.1.5.5.7.3.5 时间印证
ASNOID_EXTKEYUSE_IPSEC | 0x0d000007 | 1.3.6.1.5.5.7.3.7 IPsec

这些实际上不是 ASNOID，因为它们不是代表 OIDS 的整数，但它们可以在同一上下文中定义和使用。 它们是 KeyUse 的位定位值或命名位值。

ASNOID_KEYUSE_DIGSIG | 0x0000001
ASNOID_KEYUSE_NONREP | 0x0000002
ASNOID_KEYUSE_KEYENC | 0x0000004
ASNOID_KEYUSE_DATAENC | 0x0000008
ASNOID_KEYUSE_KEYAGREE | 0x0000010
ASNOID_KEYUSE_CERTSIGN | 0x0000020
ASNOID_KEYUSE_CRLSIGN | 0x0000040
ASNOID_KEYUSE_ENCONLY | 0x0000080
ASNOID_KEYUSE_DECONLY | 0x0000100

ASN1 类型编码的若干常量。 它们来自 ASN1 本身

ASN1_BIT_STRING_TYPE | (0x03)
ASN1_INTEGER_TYPE | (0x02)
ASN1_BOOLEAN_TYPE | (0x01)
ASN1_OID_TYPE | (0x06)
ASN1_SEQUENCE_TYPE | (0x30)
ASN1_DATE_TYPE | (0x17)
ASN1_UTCTIME | (0x17)
ASN1_GENERALTIME | (0x18)
ASN1_SET_TYPE | (0x31)
ASN1_PRINTABLE_STRING_TYPE | (0x13)
ASN1_TELETEX_STRING_TYPE | (0x14)
ASN1_OPTIONAL_0 | (0xa0)
ASN1_OPTIONAL_1 | (0xa1)
ASN1_OPTIONAL_2 | (0xa2)
ASN1_OPTIONAL_3 | (0xa3)


WebOpts 列表

具有相关选项定义的 WebOpts 列表包括：

HVOPT_N_ERROR (WEBOPT_32BIT+0x01004) // HVERR_... 标记（仅用于获取）

HVOPT_N_INDENT (WEBOPT_32BIT+0x01001) // 基本缩进

HVOPT_N_SBWIDTH (WEBOPT_32BIT+0x01003) // 滚动条宽度

HVOPT_N_VSPACE (WEBOPT_32BIT+0x01002) // 基本段落间隔

HVOPT_PTR_IWEB (WEBOPT_INTERFACE+0x01003) // IWeb 接口 Dox 用来获取子对象

HVOPT_RGB_LINK (WEBOPT_32BIT+0x01102) // 链接文本的颜色

HVOPT_RGB_TEXT (WEBOPT_32BIT+0x01101) // 默认文本的颜色

HVOPT_SZ_TYPE (WEBOPT_SZ+0x01001) // MIME 类型和/或字符集（仅用于设置）

HVOPT_SZ_URL (WEBOPT_SZ+0x01002) // 基本 URL（仅用于设置）

WEBOPT_32BIT 0x00020000

WEBOPT_32BIT 0x00020000

WEBOPT_32BIT_LAST 0x0002ffff

WEBOPT_32BIT_LAST 0x0002ffff

WEBOPT_ACTIVEXACTIONS (WEBOPT_32BIT+8) /* (unsigned int) 标量，

WEBOPT_ACTIVEXACTIONS (WEBOPT_32BIT+8) // (unsigned int) 标量，

WEBOPT_ANY 1 /* 无 pVal，匹配任何 opt，用于

WEBOPT_ANY 1 // 无 pVal，匹配任何 opt，用于

WEBOPT_ASN1 0x00050000

WEBOPT_ASN1_LAST 0x0005ffff

WEBOPT_AUTHBASIC (WEBOPT_SZ+4) /* (char *) 发送基本验证

WEBOPT_AUTHBASIC (WEBOPT_SZ+4) // (char *) 发送基本验证

WEBOPT_BODY (WEBOPT_INTERFACE+1)

WEBOPT_BODY (WEBOPT_INTERFACE+1) // 用于 POST 主体中

WEBOPT_CONNECTTIMEOUT (WEBOPT_32BIT+5) /* (unsigned int) 单位：milli-

WEBOPT_CONNECTTIMEOUT (WEBOPT_32BIT+5) // (unsigned int) 单位：milli-

WEBOPT_CONNTIMEOUT 在参数中指定到 _GetResponse()，

WEBOPT_CONTENTLENGTH (WEBOPT_32BIT+6) /* (long) 如果请求或

WEBOPT_CONTENTLENGTH (WEBOPT_32BIT+6) // (long) 如果请求或

WEBOPT_COPYOPTS 3 /* (boolean) 如果设置为 TRUE，将导致

WEBOPT_COPYOPTS 3 // (boolean) 如果设置为 TRUE，将导致

WEBOPT_COPYOPTS, TRUE,

WEBOPT_DEFAULTS (WEBOPT_INTERFACE+2) /* (IWebOpt *), 用于

WEBOPT_DEFAULTS (WEBOPT_INTERFACE+2) // (IWebOpt *), 用于

WEBOPT_END 0 /* 无 pVal，忽略其余，用于终止

WEBOPT_END 0 // 无 pVal，忽略其余，用于终止

WEBOPT_END));

WEBOPT_EXTRAHEADERS WEBOPT_HEADER /* 建议不使用，使用 WEBOPT_HEADER

WEBOPT_EXTRAHEADERS WEBOPT_HEADER // 建议不使用，使用 WEBOPT_HEADER

WEBOPT_FLAGS (WEBOPT_32BIT+1) /* (unsigned int) 默认值为 0

WEBOPT_FLAGS (WEBOPT_32BIT+1) // (unsigned int) 默认值为 0

WEBOPT_HANDLERDATA (WEBOPT_32BIT+2) /* (void *) 默认值为 NULL

WEBOPT_HANDLERDATA (WEBOPT_32BIT+2) // (void *) 默认值为 NULL

WEBOPT_HEADER (WEBOPT_SZ+2) /* (char *) CRLF 分隔，

WEBOPT_HEADER (WEBOPT_SZ+2) // (char *) CRLF 分隔，

WEBOPT_HEADER, me->szDateHeader,

WEBOPT_HEADER, szDateHeader,

WEBOPT_HEADER, szDateHeader,

WEBOPT_HEADERHANDLER (WEBOPT_32BIT+4) /* (PFNWEBHEADER) 默认

WEBOPT_HEADERHANDLER (WEBOPT_32BIT+4) // (PFNWEBHEADER) 默认

WEBOPT_IDLECONNTIMEOUT (WEBOPT_32BIT+7) /* (int) 时间，以 *秒* 为单位

WEBOPT_IDLECONNTIMEOUT (WEBOPT_32BIT+7) // (int) 时间，以 *秒* 为单位

WEBOPT_INTERFACE 0x00030000

WEBOPT_INTERFACE 0x00030000

WEBOPT_INTERFACE_LAST 0x0003ffff

WEBOPT_INTERFACE_LAST 0x0003ffff

WEBOPT_METHOD (WEBOPT_SZ+1) /* (char *) 默认值为 "GET"

WEBOPT_METHOD (WEBOPT_SZ+1) // (char *) 默认值为 "GET"

WEBOPT_PROXYSPEC (WEBOPT_SZ+3) /* (char *) proxyspec 格式

WEBOPT_PROXYSPEC (WEBOPT_SZ+3) // (char *) proxyspec 格式

WEBOPT_REMOVED 2 /* 无 pVal，跳过，已删除

WEBOPT_REMOVED 2 // 无 pVal，跳过，已删除

WEBOPT_RESERVED 0

WEBOPT_RESERVED 0

WEBOPT_RESERVED_LAST 0x0ffff

WEBOPT_RESERVED_LAST 0x0ffff

WEBOPT_SOMETHING, someval,

WEBOPT_SOMETHING2, someval2,

WEBOPT_SSL_32BIT 0x00022000

WEBOPT_SSL_32BIT_LAST 0x000221ff

WEBOPT_SSL_ALLOWED_CIPHER_SUITES (WEBOPT_SSL_32BIT+2)

WEBOPT_SSL_ALLOWED_CIPHER_SUITES 多个选项以提供顺序列表

WEBOPT_SSL_ALLOWED_VERSIONS (WEBOPT_SSL_32BIT+3)

WEBOPT_SSL_ALLOWED_CIPHER_SUITES 多个选项以提供顺序列表

WEBOPT_SSL_INTERFACE 0x00032000

WEBOPT_SSL_INTERFACE_LAST 0x000321ff

WEBOPT_SSL_SEC_INFO (WEBOPT_SSL_VARIABLE+sizeof(SSLInfo))

WEBOPT_SSL_SEC_INFO 获取 SSLInfo 结果的备选方式

WEBOPT_SSL_SESSIONDB (WEBOPT_SSL_INTERFACE + 2)

WEBOPT_SSL_SESSIONDB 已实例化的会话接口

WEBOPT_SSL_SZ 0x00012000

WEBOPT_SSL_SZ_LAST 0x000121ff // 511 个可能选项

WEBOPT_SSL_TRUST_MODE (WEBOPT_SSL_32BIT+1)

WEBOPT_SSL_TRUST_MODE 未设置或设置为 SSL_TRUST_MODE_FAIL。 如果

WEBOPT_SSL_TRUST_MODE 设置为 SSL_TRUST_MODE_CHECK，则将关闭该连接。

WEBOPT_SSL_TRUST_MODE 对于信任错误指定常规行为。

WEBOPT_SSL_TRUST_MODE，以及调用协商还是再协商。 以下三项

WEBOPT_SSL_VARIABLE 0x10010000

WEBOPT_SSL_VARIABLE_LAST 0x1001f000

WEBOPT_SSL_WANT_X509_CHAIN (WEBOPT_SSL_32BIT+4)

WEBOPT_SSL_WANT_X509_CHAIN 设置此选项以获取已创建的 X509Chain

WEBOPT_SSL_X509_CHAIN (WEBOPT_SSL_INTERFACE+1)

WEBOPT_SSL_X509_CHAIN 选项中引用

WEBOPT_STATUSHANDLER (WEBOPT_32BIT+3) /* (PFNWEBSTATUS) 默认值

WEBOPT_STATUSHANDLER (WEBOPT_32BIT+3) //* (PFNWEBSTATUS) 默认值

WEBOPT_SZ 0x00010000

WEBOPT_SZ 0x00010000

WEBOPT_SZ_LAST 0x0001ffff

WEBOPT_SZ_LAST 0x0001ffff

WEBOPT_USERAGENT (WEBOPT_SZ+5) /* (char *) 用户代理字符串，如果

WEBOPT_USERAGENT (WEBOPT_SZ+5) // (char *) 用户代理字符串，如果

WEBOPT_VARBUFFER 0x00040000

WEBOPT_VARBUFFER_LAST 0x0004ffff

WEBOPT_VARIABLE 0x10000000

WEBOPT_VARIABLE 0x10000000

WEBOPT_VARIABLE_INC 0x00001000

WEBOPT_VARIABLE_LAST 0x1ffff000

WEBOPT_VARIABLE_LAST 0x1ffff000

WEBOPT_X509_32BIT 0x00022200

WEBOPT_X509_32BIT_LAST 0x000223ff

WEBOPT_X509_ASN1 0x00052000

WEBOPT_X509_ASN1_LAST 0x00052fff

WEBOPT_X509_BRANCH_CERTS (WEBOPT_X509_ASN1+2)

WEBOPT_X509_BRANCH_CERTS ...

WEBOPT_X509_BRANCH_CERTS 中间证书可能是

WEBOPT_X509_CHAIN_CERT (WEBOPT_X509_ASN1+4)

WEBOPT_X509_CHAIN_CERT 选项类型。 排序通常有效

WEBOPT_X509_CHAIN_CERT 这是一个有些奇怪的 WEBOPT 类型。 在

WEBOPT_X509_EXT_KEY_USE (WEBOPT_X509_32BIT+2)

WEBOPT_X509_EXT_KEY_USE 之后，一组 ASN1OID（请参阅 AEEASN1OIDs.h）

WEBOPT_X509_EXT_KEY_USE 选项。 或者，无论

WEBOPT_X509_EXT_KEY_USE 还是 X509CHAIN_CRIT EXT_KEY_USE，将

WEBOPT_X509_HOST (WEBOPT_X509_SZ+1)

WEBOPT_X509_HOST 设置主机名以比较主机名

WEBOPT_X509_HOST 设置。

WEBOPT_X509_KEY_USE (WEBOPT_X509_32BIT+3)

WEBOPT_X509_KEY_USE 单个位图，提供

WEBOPT_X509_KEY_USE 的预期用途。 对于根和

WEBOPT_X509_LEAF_CERT (WEBOPT_X509_ASN1+3)

WEBOPT_X509_LEAF_CERT 这是您正在实际尝试的证书

WEBOPT_X509_MAX_CHAIN (WEBOPT_X509_32BIT+1)

WEBOPT_X509_MAX_CHAIN 而不是

WEBOPT_X509_MAX_CHAIN，我们将链接的最大长度。 不会链接以前的

WEBOPT_X509_OVERRIDE (WEBOPT_X509_VARIABLE + sizeof(X509TrustOverride))

WEBOPT_X509_OVERRIDE 您可将使用其中的几个覆盖

WEBOPT_X509_ROOT_CERTS (WEBOPT_X509_ASN1+1)

WEBOPT_X509_ROOT_CERTS 指示这是已信任的根证书

WEBOPT_X509_SZ 0x00012200

WEBOPT_X509_SZ_LAST 0x000123ff

WEBOPT_X509_VARBUFFER 0x00042000

WEBOPT_X509_VARBUFFER_LAST 0x00042fff

WEBOPT_X509_VARIABLE 0x10020000

WEBOPT_X509_VARIABLE_LAST 0x1002f000


BREW 示例应用程序

BREW 软件开发包 (BREW SDKTM) 包含若干使用 BREW 创建的示例应用程序，演示了 BREW 应用程序开发中常用的许多接口和控件的用法。 这些示例应用程序位于 <BREW\Examples> 目录中， 它们的用途是帮助识别使各个应用程序完成其目标任务的 BREW API 和控件，并从用户角度说明各个 BREW 应用程序的功能。

注意： BREW SDK 提供的示例源代码主要用于演示 BREW 数据结构和函数的用法。 尽管已对每个示例应用程序进行了全面测试，但由于示例应用程序功能不全，因而源代码将无法达到 TRUE BREWTM的测试要求。

包括以下 BREW 示例应用程序：

Expense Tracker | 说明一个简单的费用跟踪应用程序，可使设备用户记录新增费用（按支付类型）。 这些费用可以保存在文件中，以供需要时加载和查看。
MediaPlayer | 说明一个能播放声音和视频剪辑（包括您使用该应用程序记录的音频剪辑）的多媒体应用程序。 此外还可以显示静态图形图像。 它将演示各种标准控件，如播放、快进、倒回、停止、 暂停和记录等。
NetDiagnostics | 说明一个应用程序，允许设备用户使用传输控制协议/因特网协议 (TCP/IP)、用户数据报协议/因特网协议 (UDP/IP) 和超文本传输协议 (HTTP) 执行回声测试。
Road Warrior | 说明一个可访问 web 服务器并提供 San Diego 主要高速公路实时交通数据的应用程序。 Web 服务器 URL 和高速公路均可配置。
WhiteBoard | 说明一种“虚拟白板”应用程序，允许用户绘制各种大小和颜色的几何形状。 形状大小受设备屏幕大小的限制，颜色选择则受设备支持的颜色深度限制。


Expense Tracker

Expense Tracker 是一种旅行费用跟踪应用程序，使得设备用户能够记录指定时期内的费用。 用户可以跟踪交易日期、支付类型和购买金额，并输入费用说明， 还可以对整个时期内的费用或逐个交易进行审核。 在将所有费用输入数据库后，用户可以生成一个可在屏幕上查看的文本文件报告。

注意： 此示例应用程序的主要目标设备是 Sharp Z-800。如果您在 Emulator 上运行此程序，请选择 Sharp Z-800 设备图像以获得最佳效果。


Expense Tracker 说明

下表列出了 Expense Tracker 开发过程中使用的接口和控件，以及在手持设备上运行该应用程序所需的文件。

使用的接口 | 使用的控件 | 手持设备上需要的文件
IDatabase IDBMgr IDBRecord IFile IFileMgr | IDateCtl IDialog IStatic ITextCtl | expensetracker.bar expensetracker.mif expensetracker.mod expensetracker.sig


在手持设备上运行 Expense Tracker

在研究驱动 Expense Tracker 的底层代码之前，让我们先从用户的角度审视该应用程序；
即，它是如何在手持设备上运行的。

运行 Expense Tracker

  1. 运行 BREW Emulator，确保 MIF 目录设置指向 <BREW\Examples>。
  2. 选择 Expense Tracker 应用程序。

    3. BREW 将加载 Expense Tracker 小程序（即 Expense Tracker 小程序动态链接库 (DLL)），并启动该应用程序。 此时将打开一个溅射屏幕，并出现与以下显示类似的屏幕：

  3. 从 Expense Tracker 主菜单，可以执行以下功能：

    4. 选择选项 | 执行操作
Add New(添加新记录) | 将新的费用记录输入数据库。 有关说明，请参阅Add New(添加新费用)。
View(查看) | 查看并编辑（如果有必要）当前时期的现有费用记录。 有关说明，请参阅查看费用或Edit Expense(编辑费用记录)。
Option(选项) | 加载和查看现有费用报告，并将数据库中的当前费用保存到平面文件中，以供查看。 有关说明，请参阅保存和加载费用报告。
Help(帮助) | 有关使用 Expense Tracker 的信息，请查看联机说明。
About(关于) | 查看 Expense Tracker 的版权和版本信息。

  4. 要返回上一屏幕，请按 CLR。
  5. 任何时候要停止小程序，请按End(结束)。

Add New(添加新费用)

“添加新记录”菜单选项使您可以逐个记录各次交易的费用信息。 也就是说，每项费用交易在数据库中是一个独立的记录。 对于每项费用，您都可以存储交易发生的日期、使用的支付类型、金额以及简要说明。

Add New(添加新费用)

  1. 从 Expense Tracker 主菜单中选择 Add New(添加新记录)。

    2. 此时将打开“添加新记录”屏幕。

  2. Date(日期)默认为当天日期。 如果需要更改，则突出显示要更改的值，然后按“向上”
    或“向下”箭头键，增大或减小该值。

    3. 注意： 要前进至下一字段，请按“向右”箭头键。

  3. 对于Type(类型)，请按“向上”或“向下”箭头键滚动显示支付类型，直至显示正确的类型。 可用类型包括“现金”、“信用卡”、“支票”和“借记卡”。
  4. 对于Amount(金额)，请使用数字键输入值，然后按下“向右”箭头键接受金额。 输入金额后，该值将居左回填。 例如，要输入金额 $200.35，则应输入 20035。 要输入金额 50 美分，则应输入 50。
  5. 对于Desc(说明)，您可以输入至多 16 个字符来说明费用。
  6. 完成后，请按下Select(选择)。
  7. 要添加费用，请按下Done(完成)。

    8. 此时将再次打开 Expense Tracker 主菜单。

查看费用

Expense Tracker 主菜单中的View(查看)选项，使您可以查看指定日期范围内记录的费用。
您还可以查看特定支付类型或所有支付类型的全部交易。

注意： 费用记录将保留在数据库中，直至您将它们保存到平面文件报告中。 这时，将清除该日期范围内的数据库。

查看费用

  1. 从 Expense Tracker 主菜单中选择View(查看)。

    2. 此时将打开View Parameters(查看参数)屏幕。

  2. 对于Type(类型)，请选择费用的支付类型（全部、现金、信用卡、支票和借记卡）。 如果选择的类型不是“全部”，则只能查看该类型的费用。
  3. 在From(从)和To(至)中，输入您要查看选定类型费用的日期范围。
  4. 显示正确的参数后，请按下View(查看)。

    5. 此时将打开Expense(费用)屏幕，显示指定日期范围内的费用，并在底部显示总计。

  5. 通过此屏幕，您可以执行以下操作：
    • 要查看各项费用的说明，请按“向上”或“向下”箭头键。
    • 要返回“查看”屏幕，请按 CLR 键。
    • 要编辑费用，请突出显示该费用并按下Select(选择)。 请参阅下文 Edit Expense(编辑费用记录) 。

Edit Expense(编辑费用记录)

添加和查看费用后，您可以根据需要，在将它们保存到报告之前进行编辑。

Edit Expense(编辑费用)

  1. 按照前述步骤，查看您要编辑的费用。

            2.

  2. 突出显示您要编辑的费用，并按下Select(选择)。

    3. 此时将打开Edit Expense(编辑费用)屏幕。

  3. 使用与添加费用相同的方法，编辑其信息。
  4. 完成编辑费用记录后，按下Select(选择)并执行以下操作之一：
    • 按下Erase(删除)，删除该记录。
    • 按下Done(完成)，保存更改内容。

      • 此时将再次打开Expense(费用)屏幕，并在总计中反映更改内容。

保存和加载费用报告

在完成输入特定时期的费用后（例如商务旅行结束时），您可以将费用保存到平面文件报告中，以供将来查看。 保存该报告后，将删除单个费用记录，以节省设备空间。 您可以随时加载所保存的报告，以查看费用信息。

加载现有的费用报告

  1. 从 Expense Tracker 主菜单中，选择Options(选项)。

    2. 此时将打开Options(选项)菜单屏幕。

    注意： 如果自上次保存报告后再没有添加过任何费用记录，则菜单中将不显示Save Report(保存报告)选项。

  2. 选择Load Report(加载报告)。

    3. 此时将打开Load Report(加载报告)屏幕。

  3. 突出显示您要加载的报告，并按下Select(选择)。

    4. 此时将打开Report(费用报告)屏幕。

  4. 完成查看报告后，请按下Select(选择)。

    5. 此时将关闭Report(费用报告)屏幕，并再次打开 Expense Tracker 主菜单屏幕。

将费用保存到费用报告中

  1. 从 Expense Tracker 主菜单中，选择Options(选项)。

    2. 此时将打开Options(选项)菜单屏幕。

  2. 选择Save Report(保存报告)。

    3. 此时将打开Save Report(保存报告)确认屏幕。

  3. 要保存报告并删除费用记录，请按下Yes(是)。

    4. 此时将保存报告，删除单个的费用记录，并再次打开Options(选项)菜单屏幕。


Expense Tracker 演示内容

Expense Tracker 演示了如何创建使用文件处理和数据库功能的 BREW 应用程序，以及 BREW SDK 提供的各种 GUI 控件。 Expense Tracker 接口使用了若干菜单，使得用户可以访问各种程序功能，其中包括向费用数据库添加新费用、执行数据库查询、编辑和删除费用，以及生成可在屏幕上查看的费用报告。

用户通过一组表单在电话屏幕上输入信息，执行输入、搜索、编辑和删除费用记录等操作。 这些表单演示了各种 BREW 控件，包括 IMenuCtl、IDateCtl、ITextCtl、IStatic，以及专为此应用程序设计的称为 CAmountCtl 的自定义控件。 表单可通过 IDialog 接口编程实现，该接口将使用 BREW 资源编辑器所创建的表单控件。

Expense Tracker 还演示了 BREW 数据库应用程序的实现，使用了 IDatabase、IDBMgr 和 IDBRecord 接口，以及用于文件处理的 IFileMgr 和 IFile。 通过使用 BREW 资源编辑器定义应用程序所用的字符串和图像值，该示例应用程序还可支持本地化。


MediaPlayer

MediaPlayer 是一种多媒体应用程序，可以播放声音和视频剪辑，显示静态图象。如果你装载了合适的CMX DLL，这种应用程序也可以录制和播放 QUALCOMM PureVoice (QCP) 音频剪辑。 可以存储多达 32 个多媒体文件，以供应用程序使用。 MediaPlayer 包括多种标准控件，如播放、快进、倒回、停止、暂停和记录。 MediaPlayer 广泛支持各种音频、视频和静态图形格式，包括 QCP、MPEG 音频层 3 (MP3)、乐器数字化接口 (MIDI)、BREW Compressed Image (BCI)、位图 (BMP)，以及包含音频和视频的数据包模式数据 (PMD)。

注意： 此示例应用程序的主要目标设备是 Sharp Z-800。如果您在 Emulator 上运行此程序，请选择 Sharp Z-800 设备图像以获得最佳效果。


MediaPlayer 说明

下表列出了 MediaPlayer 开发过程中使用的接口和控件，以及在手持设备上运行该应用程序所需的文件。

使用的接口 | 使用的控件 | 手持设备上需要的文件
IMedia | IDisplay IFile IFileMgr IMenuCtl IStatic | mediaplayer.bar mediaplayer.mif mediaplayer.mod mediaplayer.sig 此外，手持设备的 "media"目录中需要包含媒体文件。


在手持设备上运行 MediaPlayer。

在研究驱动 MediaPlayer 的底层代码之前，先从用户的角度查看该应用程序；即，它是如何在手持设备上运行的。

运行 MediaPlayer

  1. 运行 BREW Emulator，确保 MIF 目录设置指向 <BREW\Examples>。
  2. 选择 MediaPlayer 应用程序。

    3. BREW 将加载 MediaPlayer 小程序 DLL 并启动应用程序。 此时将打开一个溅射屏幕，并出现与以下显示类似的屏幕：

  3. 从 MediaPlayer 主菜单，可以执行以下功能：

    4. 选择选项 | 执行操作
Play File(播放文件) | 选择要在手持设备上运行的音频、视频或静态图形文件。 有关说明，请参阅下面的查看或播放多媒体文件。
Record QCP File(记录 QCP 文件) | 使用话筒模拟设备话筒，记录 QCP 音频文件。 有关说明，请参阅记录 QCP 音频文件。 使用“播放文件”菜单项可播放所记录的文件。
About(关于) | 查看 MediaPlayer 的版权信息。

  4. 任何时候要停止小程序，请按End(结束)。

查看或播放多媒体文件

“播放文件”菜单选项使您可以选择要在手持设备屏幕上运行的音频、视频或静态图形文件。 下面将逐一说明各种媒体类型。

播放音频文件

  1. 从 MediaPlayer 主菜单中选择Select File(播放文件)。

    2. 此时将打开Select File(选择文件)屏幕。

  2. 突出显示您要播放的音频文件（MIDI、QCP 或 MP3），并按下Select(选择)。

    3. 此时将打开与以下显示类似的屏幕。

  3. 要播放音频剪辑，请按下Select(选择)。

    4. 此时将播放声音剪辑并在底部状态栏中显示已播放的时间。

    其它控件将在下文中说明。

  4. 完成播放媒体文件后，请按下 CLR。

    5. 此时将再次打开Select File(选择文件)屏幕。

播放视频文件

  1. 在Select File(选择文件)屏幕中，突出显示您要播放的视频文件 (BCI) 并按下Select(选择)。

    2. 此时将播放该视频。

  2. 要清除屏幕并只显示该视频，请按下Select(选择)键，选择工具栏按钮Zoom(缩放)（放大镜）。

    3. 注意： Zoom(缩放)按钮只可用于 BCI 和 BMP 文件。

    此时播放视频，屏幕顶部或按钮栏将不显示信息。

  3. 按下任意键返回上一视图。
  4. 完成播放媒体文件后，请按下 CLR。

    5. 此时将再次打开Select File(选择文件)屏幕。

查看静态图像

  1. 在Select File(选择文件)屏幕中，突出显示您要查看的图像文件 (BMP) 并按下Select(选择)。

    2. 此时将出现与以下显示类似的屏幕。

  2. 要清除屏幕并只显示该图形，请按下Select(选择)键，选择工具栏按钮
    Zoom(缩放)。

    3. 此时显示图像，屏幕顶部或按钮栏将不显示信息。

  3. 按下任意键返回上一视图。
  4. 您还可以使用箭头键向左、向右、向上和向下滚动图形。
  5. 完成查看静态图形图像后，请按下 CLR。

    6. 此时将再次打开Select File(选择文件)屏幕。

  6. 要退出 MediaPlayer，请按下End(结束)。

记录 QCP 音频文件

MediaPlayer 使您可以通过设备话筒记录您的声音或其它声音，然后使用“播放文件”菜单项重放所记录的声音。 每个记录的长度没有限制；但是，由于手持设备上的内存量有限，
因此持续时间相对较短。

记录 QCP 文件

  1. 从 MediaPlayer 主菜单中选择Record QCP File(记录 QCP 文件)。

    2. 此时将打开(记录)屏幕。

    请注意，屏幕顶部有一个文件名。 这是记录要使用的文件名。 还请注意，此时按钮栏中包含一个绿色的“记录”按钮。

  2. 突出显示"记录"按钮并按下Select(选择)。

    3. “记录”屏幕将在按钮栏上显示记录时间。

  3. 如果要停止记录，请突出显示Stop(停止)按钮并再次按下Select(选择)。

    4. 该记录将使用屏幕顶部显示的名称保存。 至此，从 MediaPlayer 主菜单中选择Play File(播放文件)选项时可以选择播放该文件。


MediaPlayer 演示内容

MediaPlayer 演示了如何创建 BREW 多媒体应用程序。 BREW 程序员可使用 IMedia 和基于 IMedia 的接口构造媒体播放器，播放和记录所有多媒体格式（包括音频和视频）。 当前，如果你装载了合适的CMX DLL，它便支持 QCP 记录。 MediaPlayer 使用 IImageCtl 和 IImage 接口显示图像。 程序员提供了以下基本指导，以帮助您创建类似的应用程序。

  • 创建自己的接口（抽象基类）并在应用程序中使用。 MediaPlayer 使用了一个 IWindow 接口，所有窗口均继承于该接口。 每个窗口都可以刷新其本身并处理发送给它的事件。 共有三个窗口：
    • 主窗口管理主菜单。
    • “文件列表”窗口使用户可以从列表中选择媒体文件。
    • “播放器”窗口启用播放和记录控件。
  • 使用各种控件，如 IMenuCtl、IImageCtl 和 IStatic。 MediaPlayer 还向您展示了如何使用 IDisplay 实现自己的进度条控件。
  • 通过 ISHELL_Resume() API（用于将一个大任务分割成若干小程序块）启用协作式多任务处理。 在 MediaPlayer 中，IWindow 为异步刷新。 MediaPlayer 还演示了应用程序中异步计时器的用法。
  • 在应用程序中使用用户自定义事件。 例如，MediaPlayer 使用用户自定义的事件创建了基于 IMedia 的类。


NetDiagnostics

应用程序 NetDiagnostics 允许设备用户使用 TCP/IP 和 UDP/IP 协议对用户指定的主机或 IP 地址执行回声测试，以及可返回指定 URL 和传输速度等信息的 HTTP 测试。

注意： 此示例应用程序的主要目标设备是 Sharp Z-800。如果您在 Emulator 上运行此程序，请选择 Sharp Z-800 设备图像以获得最佳效果。


NetDiagnostics 说明

下表列出了 NetDiagnostics 开发过程中使用的接口和控件，以及在手持设备上运行该应用程序所需的文件。

使用的接口 | 使用的控件 | 手持设备上需要的文件
INetMgr ISocket IHtmlViewer IWeb IWebOpts IWebResp ISource ISourceUtil IPeek IGetLine | IHtmlViewer | netdiagnostics.bar netdiagnostics.mif netdiagnostics.mod netdiagnostics.sig


在手持设备上运行 NetDiagnostics

在研究驱动 NetDiagnostics 的底层代码之前，先从用户的角度查看该应用程序；即，它是如何在手持设备上运行的。

运行 NetDiagnostics

  1. 运行 BREW Emulator，确保 MIF 目录设置指向 <BREW\Examples>。
  2. 选择 NetDiagnostics 应用程序。

    3. BREW 将加载 NetDiagnostics 小程序 DLL 并启动应用程序。 此时将打开一个溅射屏幕，并出现与以下显示类似的屏幕：

  3. 从 NetDiagnostics 主菜单，可以执行以下功能：

    4. 选择选项 | 执行操作
Echo Tests(回声测试) | 使用 TCP/IP 或 UDP/IP 协议在设备上执行回声测试。 请参阅下文执行回声测试。
HTTP Tests(HTTP 测试) | 测试用户指定 URL 的连接响应信息。 有关说明，请参阅执行 HTTP 测试。
Help(帮助) | 查看使用 NetDiagnostics 的联机说明。
About(关于) | 查看 NetDiagnostics 的版权和版本信息。

  4. 任何时候要停止小程序，请按下 CLR。

执行回声测试

“回声测试”菜单项允许您为测试指定一系列参数，如目标主机或 IP 地址、要传输的文本消息，以及要测试的网络协议类型。 在运行测试并完成测试网络访问后，您可以选择查看响应信息，以及响应时间信息。

运行回声测试

  1. 从 NetDiagnostics 主菜单中选择Echo Tests(回声测试)。

    2. 此时将打开Echo Tests(回声测试)屏幕。

  2. 要更改目标主机或 IP 地址，请突出显示Host(主机)，并按下Select(选择)。

    3. 此时地址将变成可编辑字段。 您可以执行以下文本编辑功能：

    执行编辑
    执行操作
    输入文本字符
    在设备键盘上按右箭头键、左箭头键以及文本字符键。
    输入数字
    执行以下步骤：
    • 按下Select(选择)，突出显示Done
      (完成)      。
    • 按下右箭头键以突出显示 Multitap。
    • 按下Select(选择)。
    • 突出显示Numbers(数字)并按下Select(选择)。
    • 此时即可使用设备键盘输入数字。
    输入符号
    执行以下步骤：
    • 按下Select(选择)，突出显示Done
      (      完成)。
    • 按下右箭头键以突出显示 Multitap。
    • 按下Select(选择)。
    • 突出显示Symbols(符号)并按下Select(选择)。
      此时屏幕将显示一系列符号，以及它们在设备键盘上的关联按键。
    • 要查看更多的符号选择，请按下“向下”箭头键。
    • 使用设备键盘输入相关符号。

  3. 要更改传输的消息，请突出显示Message(消息)并按下Select(选择)。

    4. 此时该消息将变成可编辑字段，并具有与“主机”字段相同的编辑功能。

  4. Show Response(显示响应)复选框用于指示是否要查看来自主机的响应。 您可以通过突出显示该复选框并按下Select(选择)来更改此选项。
  5. Show Timings(显示计时)复选框用于指示是否要查看响应时间信息，如总的传输时间（毫秒）、发送时间（每秒发送指定位数的毫秒数）和接收时间（例如 10 ms @ 2000 bps）。 您可以通过突出显示该复选框并按下Select(选择)来更改此选项。
  6. 选择 TCP 或 UDP 因特网协议。 它是一个单选按钮类型设置。 您必须选择一个或另一个选项，但不能同时选择两者。 要更改选择，请突出显示要用于测试的协议并按下Select(选择)。

    7. 注意： 要在屏幕上查看字段定义，请突出显示Info(信息)并按下Select(选择)。 完成后，按下 CLR。

  7. 完成选择测试参数后，按下Start(开始)。

    8. 此时将运行测试，并出现与以下显示类似的屏幕。

  8. 要清除测试屏幕，请按下 CLR。

    9. 此时将再次打开 NetDiagnostics 主菜单。

执行 HTTP 测试

HTTP Tests(HTTP 测试)菜单项使您可以指定一系列用于测试到指定 URL 的 HTTP 连接的参数。 测试运行时，您可以选择查看响应信息以及响应时间信息。

运行 HTTP 测试

  1. 从 NetDiagnostics 主菜单中选择 HTTP Tests(HTTP 测试)。

    2. 此时将打开HTTP Tests(HTTP 测试)屏幕。

  2. 要更改目标 URL，请突出显示 URL 并 按下Select(选择)。

    3. 此时，URL 将变成可编辑字段。 您可以按照前面步骤中的说明，执行相同的文本编辑功能。

  3. Show Response(显示响应)复选框用于指示是否要查看来自目标 URL 的 HTTP 连接响应。 您可以通过突出显示该复选框并按下Select(选择)来更改此选项。
  4. Show Timings(显示计时)复选框用于指示是否要查看响应时间信息。 您可以通过突出显示该复选框并按下Select(选择)来更改此选项。

    5. 注意： 要在屏幕上查看字段定义，请突出显示Info(信息)并按下Select(选择)。 完成后，请按下 CLR。

  5. 完成选择测试参数后，请按下Start(开始)。

    6. 此时将运行测试，并出现与以下显示类似的屏幕。

  6. 要清除测试屏幕，请按下 CLR。

    7. 此时将再次打开 NetDiagnostics 主菜单。


NetDiagnostics 演示内容

NetDiagnostics 演示了如何创建使用各种 BREW 网络接口的 BREW 应用程序。 GUI 是由 IHtmlViewer 接口驱动，该接口允许在电话屏幕上查看 HTML 文档。 通过访问存储在电话文件系统中的 HTML 文件并将其显示在 IHtmlViewer 对象中，即可生成各个应用程序屏幕。 用户通过选择 HTML 页中显示的各种链接定位该接口。

该应用程序可执行两类网络连接测试：

测试 | 允许用户执行的操作
Echo Tests(回声测试) | 向指定的回声服务器发送 TCP 或 UDP 消息。 用户可以在屏幕上显示的 HTML 表单中指定主机、消息文本、传输类型（TCP 或 UDP）以及响应参数。 初始化测试后， 应用程序将显示传输的状态、返回的消息以及传输统计数据。
HTTP Tests (HTTP 测试) | 使用 HTTP 协议访问因特网地址。 用户可以在屏幕上显示的 HTML 表单中指定 URL 和显示参数。 初始化测试后，应用程序将显示传输的状态、返回的 HTML 源代码以及传输统计数据。

使用 INetMgr、ISocket、IWeb、IWebOpts 和 IWebResp 等 BREW API 接口可处理网络连接。 HTML 文本则由 IHtmlViewer、ISource、ISourceUtil、IPeek 和 IGetLine 接口解析和
显示。


Road Warrior

应用程序 Road Warrior 可连接加利福尼亚交通部的 Web 服务器，并提供圣地亚哥主要高速公路的实时交通数据。 Web 服务器 URL 和高速公路均可配置。

注意： 此示例应用程序的主要目标设备是 Sharp Z-800。如果您在 Emulator 上运行此程序，请选择 Sharp Z-800 设备图像以获得最佳效果。


Road Warrior 说明

下表列出了 Road Warrior 开发过程中使用的接口和控件，以及在手持设备上运行该应用程序所需的文件。

使用的接口 | 使用的控件 | 手持设备上需要的文件
IDisplay IFile IFileMgr IShell IWeb IWebResp | IMenuCtl | roadwarrior.bar roadwarrior.dat roadwarrior.mif roadwarrior.mod roadwarrior.sig


在手持设备上运行 Road Warrior

在研究驱动 Road Warrior 的底层代码之前，先从用户的角度查看该应用程序；即，它是如何在手持设备上运行的。

运行 Road Warrior

  1. 运行 BREW Emulator，确保 MIF 目录设置指向 <BREW\Examples>。
  2. 选择 Road Warrior 应用程序。

    3. BREW 将加载 Road Warrior 小程序 DLL 并启动应用程序。 此时将打开一个溅射屏幕，并出现与以下显示类似的屏幕：

  3. 突出显示要获取其速度信息的高速公路和方向，并按下Select(选择)。

    4. 应用程序将连接至 web 服务器，并打开以下屏幕。

    顶部的滚动横幅显示了选定的高速公路和方向，以及访问 web 服务器的日期和时间。 每个十字路口左侧的数字表示当前的交通速度。 在沿十字路口滚动时，屏幕底部的图形将反复变化，以近似显示每个十字路口的交通量（如下所示）。

  4. 任何时候要停止小程序，请按下End(结束)。


Road Warrior 演示内容

Road Warrior 是一种向用户提供实时交通速度的应用程序。 虽然它只提供圣地亚哥高速公路的数据，但可用作针对其它地区的类似应用程序的模板。

Road Warrior 演示了如何使用 IWeb 接口从公用 web 服务器获取信息，然后解析结果 HTML，以准备向用户显示的数据。 它还演示了以下内容：

  • 它显示了如何向用户反馈当前正在运行的潜在耗时的网络操作，以及如何使用户取消网络连接。
  • 它使用静态和动态图像，帮助美化了原本基于文本的应用程序。
  • 它显示了应如何处理 BREW 应用程序的中止和恢复，包括对控件活动状态的管理以及动画的停止和开始。
  • 它使用了 IMenuCtl 接口来显示信息和获取用户输入，包括自定义按键按下处理。
  • 它提供了示例来说明如何在应用程序多个正在运行的不同会话之间持久保存用户首选项。
  • 它演示了如何执行简单的文件读取操作，包括一次性读入大型文本块以提高文件系统性能的机制。
  • 它在运行时查询 BREW 设备，并根据查询信息确定屏幕颜色深度和配置菜单控件样式。
  • 它提供了示例来说明如何将字符串变成字符串资源，以便能够方便地将应用程序翻译成其它语言。
  • 最重要的是，Road Warrior 演示了一个已通过 TRUE BREW 测试并应用于商用 BREW 环境的现实的应用程序。


WhiteBoard

这种“虚拟白板”应用程序允许用户绘制各种大小和颜色的几何图形。 您可以随时擦除全部或部分绘图。 形状大小受设备屏幕大小的限制，颜色选择则受设备支持的颜色深度限制。

注意： 此示例应用程序的主要目标设备是 Sharp Z-800。如果您在 Emulator 上运行此程序，请选择 Sharp Z-800 设备图像以获得最佳效果。


WhiteBoard 说明

下表列出了 WhiteBoard 开发过程中使用的接口和控件，以及在手持设备上运行该应用程序所需的文件。

使用的接口 | 使用的控件 | 手持设备上需要的文件
IBitmap IDisplay IGraphics IImage | IMenuCtl IStatic | whiteboard.bar whiteboard.mif whiteboard.mod whiteboard.sig


在手持设备上运行 WhiteBoard

在研究驱动 WhiteBoard 的底层代码之前，先从用户的角度查看该应用程序；即，它是如何在手持设备上运行的。

运行 WhiteBoard

  1. 运行 BREW Emulator，确保 MIF 目录设置指向 <BREW\Examples>。
  2. 选择 WhiteBoard 应用程序。

    3. BREW 将加载 WhiteBoard 小程序 DLL 并启动应用程序。 此时将打开一个溅射屏幕，并出现与以下显示类似的屏幕：

  3. 从 WhiteBoard 主菜单，可以执行以下功能：

    4. 选择选项 | 执行操作
Draw(绘制) | 使用从“选项”菜单项中选择的形状和颜色在 whiteboard 上绘制。 有关说明，请参阅在 whiteboard 上绘制。
Tools(工具) | 指定用于绘制和填充的图形和颜色。 有关说明，请参阅设置绘制选项。
Help(帮助) | 查看使用 WhiteBoard 的联机说明。
About(关于) | 查看 WhiteBoard 的版权和版本信息。

  4. 任何时候要停止小程序，请按下End(结束)。

设置绘制选项

Tool(工具)菜单选项使您可以选择要绘制的图形、边框和填充颜色。 以下是可用的图形， 其后是绘制每种图形的说明。

图形 | 示例
线段 |
折线 |
弧线 |
圆 |
椭圆 |
饼图 |
矩形 |
三角形 |
多边形 |

注意： 除了以上所示的图形之外，封闭图形（如圆、矩形和多边形）可以填充黑色或其它颜色， 线段或图形边框也可以指定颜色。

选择图形

  1. 从 WhiteBoard 主菜单中选择Tools(工具)。

    2. 此时将打开Tools(工具菜单)屏幕。

  2. 突出显示图形，按下Select(选择)。

    3. 此时将打开Shapes(图形菜单)屏幕。

  3. 选择要绘制的图形类型。 下表说明了“图形”菜单下三个菜单项中的可用图形。

    4. 选择菜单项 | 绘制图形
线段 | 线段 折线 弧线
填充图形 | 圆 椭圆 矩形 三角形 多边形
非填充图形 | 圆 椭圆 饼图 矩形 三角形 多边形

  4. 选择图形后，请执行以下操作之一：
    • 如果要更改边框颜色，或选择了封闭图形（如圆）并要更改填充颜色，请参阅下文选择边框或填充颜色。
    • 如果不需更改颜色，请按下 CLR。

      • 此时将打开 WhiteBoard 主菜单。

选择边框或填充颜色

  1. 从“工具”菜单中选择Colors(颜色)。

    2. 此时将打开Select Colors(选择颜色)屏幕。

    所选图形将显示在屏幕中；在本例中，选择的是非填充矩形图形。 如果选择了填充图形，则屏幕还将显示“模式”字段，使您可以切换边框颜色和填充颜色。

  2. 要更改边框颜色，请在Mode(模式)字段中选择“边框”，并指定要使用的颜色的 RGB 值。
  3. 要更改填充颜色，请在Mode(模式)字段中选择“填充”，并指定要使用的颜色的 RGB 值。
  4. 完成选择图形颜色后，按下Done(完成)。

    5. 此时将打开 WhiteBoard 主菜单屏幕。

在 whiteboard 上绘制

使用Tools(工具)菜单选择图形或颜色（可选）后，即可使用Draw(绘制)菜单项在 whiteboard 上绘制几何图形。 您可以随时更改正在绘制的图形，并重叠图形。

在 whiteboard 上绘制

  1. 从 WhiteBoard 主菜单中选择Draw(绘制）。

    2. WhiteBoard 屏幕将进入Draw Mode(绘制模式)。

  2. 使用箭头键移动十字准线，绘制所选图形。 如下文中的绘制步骤所述，每种图形要求使用的绘制方法各不相同。

    3. 注意： 在Draw Mode(绘制模式)下，每次按下箭头键，十字准线将移动 1 像素。 要增大每次移动的距离，请按下一个数字键。 例如，要使每次按下箭头键时十字准线移动 7 像素，则应按下 7 键。

  3. 完成绘制操作后，请按下 CLR。

    4. 此时将打开 WhiteBoard 主菜单。

    注意： CLR 键还可用于在将绘图操作应用于白板之前将其删除。 有关详细信息，请参阅撤消操作。

绘制线段

  1. 将十字准线移动至线段的起点并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至线段的终点并按下Select(选择)。

    3. 此时将显示一条线段连接这两点。

绘制折线

  1. 将十字准线移动至折线的起点并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至第一条线段的终点并按下Select(选择)。

    3. 此时将出现另一个圆点。

  3. 重复步骤 2，直至到达折线终点。
  4. 绘制最后一个点时，按下Select(选择)一秒钟。

    5. 此时将显示一条折线连接这些点。

绘制弧线

  1. 将十字准线移动至显示弧线中心的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至显示弧线半径和起角的点，并按下Select(选择)。

    3. 此时将出现另一个圆点。

  3. 将十字准线移动至显示弧线终角的点，并按下Select(选择)。
  4. 再次按下Select(选择)。

    5. 此时将显示一条弧线连接这两点。

    注意： WhiteBoard 按逆时针方向绘制弧线。 因此，如果指定的弧线起角位置在 Y 轴上低于终角，则所得弧线将小于 180 度。 如果指定的弧线起角位置在 Y 轴上高于终角，则所得弧线将大于 180 度。

绘制圆

  1. 将十字准线移动至圆心点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 沿 X 轴方向将十字准线移动至用于确定圆半径的点，并按下Select(选择)。

    3. 此时将绘制一个圆。

绘制椭圆

  1. 将十字准线移动至显示椭圆中心的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至用于确定椭圆 X 半轴和 Y 半轴的点，按下Select(选择)。

    3. 此时将绘制一个椭圆。

绘制饼图

  1. 将十字准线移动至显示饼图中心的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至显示饼图半径和起角的点，并按下Select(选择)。

    3. 此时将出现另一个圆点。

  3. 将十字准线移动至显示饼图终角的点，并按下Select(选择)。
  4. 再次按下Select(选择)。

    5. 此时将显示一张饼图连接这些点。

    注意： 与弧线一样，WhiteBoard 沿逆时针方向绘制饼图。 因此，如果指定的饼图起角位置在 Y 轴上低于终角，则所得饼图将小于 180 度。 如果指定的饼图起角位置在 Y 轴上高于终角，则所得饼图将大于 180 度。

绘制矩形

  1. 将十字准线移动至显示矩形一角的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至显示矩形对角的点，并按下Select(选择)。

    3. 此时将绘制一个矩形。

绘制三角形

  1. 将十字准线移动至显示三角形一角的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 将十字准线移动至显示三角形第二个角的点，并按下Select(选择)。

    3. 此时将出现另一个圆点。

  3. 将十字准线移动至显示三角形第三个角的点，并按下Select(选择)。

    4. 此时将显示一个三角形连接这三点。

绘制多边形

  1. 将十字准线移动至显示多边形一角的点，并按下Select(选择)。

    2. 此时将出现一个闪烁的小圆点。

  2. 重复步骤 1，直至到达最后一角的点，然后再次按下Select(选择)。

    3. 此时将显示一个多边形连接这些点。

关于绘制操作的最后几点说明

除了绘制操作之外，WhiteBoard 还提供了一些可增强应用程序的功能，包括“撤消操作”
功能、“滚动显示”功能（它可使用户的绘制操作水平地延伸至设备屏幕宽度以外）和“剪切”功能。

撤消操作

绘制给定图形（例如三角形）时，角的位置将保存在设备内存中，直至绘制最终图形。 如果在图形完成之前（即设置最后一个点之前）按下 CLR，则将删除图形的所有点。

滚动显示

在“绘制模式”下，可将绘制操作延伸至设备屏幕宽度的限制以外。 屏幕底部的滚动条使您可以滚动显示设备屏幕宽度的两倍。

剪切

“剪切”功能使您可以删除绘制操作的一个矩形部分。 要剪切绘图，请在完成绘制当前图形后，在剪切矩形的一角按下Select(选择)两次。 将十字准线移动至矩形的对角，再次按下Select(选择)。 此时将删除选定矩形内的所有绘制。 使用此功能可以删除屏幕的一小部分或整个屏幕。


WhiteBoard 演示内容

WhiteBoard 演示了如何创建使用 BREW API 图形功能的 BREW 应用程序。 该示例应用程序允许用户在电话显示屏的滚动矩形绘制画布上渲染简单的几何图形。 用户可以选择各种图形、设置每个图形的边框和填充颜色。 光标用于在绘制画布上标点，以绘制所选的几何图形。

应用程序允许用户通过浏览一系列“图标列表”菜单，选择填充或非填充绘制图形。 另外还提供了表单，允许用户设置和查看特定图形的颜色设置。 在选定图形和颜色设置之后，用户通过在画布上标出代表绘制图形所需的顶点，即可绘制图形。

BREW IGraphics 接口广泛用于绘制线段、折线、弧线、圆、椭圆、矩形、三角形、饼图，
以及不同边数的多边形。 画布是通过两个图形缓冲区实现的：屏幕显示缓冲区和单独的幕后 IBitmap 缓冲区。 屏幕显示图形缓冲区用于显示绘制光标和已标出的点。 图形被渲染至 IBitmap 缓冲区，并在需要时更新到电话屏幕缓冲区中。 通过 AEE_RO_XOR 光栅操作，
可将使用底层图像、光标和点运动在电话屏幕上绘制的光标图像和点透明地显示在屏幕上。

IBitmap 幕后缓冲区比电话屏幕宽，可使画布在水平方向滚动。